Table of Contents

3. Error Handling, Memory System, Standard Output, Quadruple Precision - Error,Memory,Print,VQuad

DevTools provides facilities for detecting and handling errors in module functions using the Error module. The Memory module provides the user with access to the functions used within DevTools for memory management. The Print module allows the user to redirect console output to a file. The VQuad module allows the user to operate on quadruple precision floating point variables of type Vquad.

The error facilities have been designed to minimize the overhead of error checking and to allow the use of user defined error handler functions. Conditional compilation options exist to include more extensive error checking during the software development phase which can be removed from production software for performance optimization.

Each module in DevTools contains a function to return the current error flag (type Vint) of an object. For example, to return the error flag for a Contour object, use vis_ContourError as follows. 

   Vint errorflag;
   errorflag  = vis_ContourError (contour);
When an error is detected by an object, the object error flag is set to the appropriate error flag value. When the error query function (eg. vis_ContourError) is called, the current error flag is returned and the flag is reset to SYS_ERROR_NONE. Possible error flags are the following, 

SYS_ERROR_NONE          No error recorded.  This value is zero
SYS_ERROR_VALUE         Argument with an improper value
SYS_ERROR_ENUM          Argument is not a valid option
SYS_ERROR_OBJECTTYPE    Argument is not a valid object type
SYS_ERROR_MEMORY        Memory allocation failure
SYS_ERROR_NULLOBJECT    A NULL object pointer has been encountered
SYS_ERROR_FILE          Argument is not a valid file name
SYS_ERROR_COMPUTE       A compute error has occurred
SYS_ERROR_OPERATION     An operation is illegal in current state
SYS_ERROR_OVERFLOW      A data structure overflow has occurred
SYS_ERROR_UNDERFLOW     A data structure underflow has occurred
SYS_ERROR_UNKNOWN       An error of unknown type has occurred
SYS_ERROR_FORMAT        Improper or incomplete file format or contents
SYS_ERROR_SEVERE        Severe internal error has occurred
Also, each DevTools component library defines error flags, such as the VisTools error flag VIS_ERROR_ENUM, which have the same meaning and value as the related system error flags.

The Error module performs the error handling tasks. The default error handler prints error information to standard output. The user may install a custom error handler. Also the Error module can be used to return a descriptive string corresponding to a given error flag.

Error checking within an object can be a performance consideration when a function may be called literally hundreds of millions of times. This is most likely the case in query functions which may be retrieving data from the private data of an object. In this case the user may define VKI_CHECK_ERRS at compile time to include error checking code during the software development phase which can be removed from production software when it can be shown that functions of interest are used error free. In summary, the compile time definitions related to error checking are the following. 

VKI_CHECK_ERRS    Include additional error checking
Table of Contents

3.1 Error Handling - Error

The Error module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the Error module represents a single system wide data structure which is used by all DevTools objects and perhaps user code when calling an error handler. Functions exist to install a user defined error handler or a default DevTools error handler. For convenience, a user defined error pointer may also be installed and queried. The information passed to the error handler is the name of the calling function, the error flag and a message string.

The Error module supports the following functions.

Use vut_ErrorSetHandler to install a user defined error handler. The function vut_ErrorHandler is the default installed error handler. It simply prints the error information to standard output. The function vut_ErrorCall calls the installed error handler. Any DevTools module calls vut_ErrorCall internally when an error is detected. Of course the user may call vut_ErrorCall if it is desired to use the Error module in the host application error system.

Table of Contents

3.2 Function Descriptions

The currently available Error functions are described in detail in this section.

Table of Contents , Error

NAME

*vut_ErrorCall - call installed error handler

C SPECIFICATION

void vut_ErrorCall (const Vchar *funcname,
                    Vint errorflag,
                    const Vchar *message)

INPUT ARGUMENTS

funcname     Name of calling function
errorflag    Error flag
message      Message string

OUTPUT ARGUMENTS

None

DESCRIPTION

The function passes the input arguments to the installed error handler.

To invoke the default error handler directly call 

     void vut_ErrorHandler (const Vchar *funcname,
                            Vint errorflag,
                            const Vchar *message)
The default error handler prints the name of the calling function, the integer error flag and the message string to standard output. Note that standard output may be redirected to a file descriptor using the Print module function vut_PrintSetFile. If the message string is a NULL or an empty string, then the descriptive error string is printed.

Table of Contents , Error

NAME

vut_ErrorSetHandler - install a pointer to the error handler

C SPECIFICATION

void vut_ErrorSetHandler (void (*func) (const Vchar*, Vint, const Vchar*))

INPUT ARGUMENTS

func         Pointer to error handler

OUTPUT ARGUMENTS

None

DESCRIPTION

Install a pointer to a user defined error handler function. If a NULL pointer is passed, the default function vut_ErrorHandler is installed. Please see vut_ErrorHandler for a description of the arguments to the error handler.

Table of Contents , Error

NAME

vut_ErrorGetHandler - query pointer to the current error handler

C SPECIFICATION

void vut_ErrorGetHandler (void (**func) (const Vchar*, Vint, const Vchar*))

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

func         Pointer to error handler

DESCRIPTION

Query for the pointer to the current error handler function. Set a user defined error handler using vut_ErrorSetHandler.

Table of Contents , Error

NAME

vut_ErrorSetObject - set a pointer to the error object

C SPECIFICATION

void vut_ErrorSetObject (Vobject *object)

INPUT ARGUMENTS

object       Pointer to user defined object

OUTPUT ARGUMENTS

None

DESCRIPTION

Install a pointer to a user defined error object. Query for the current user defined object pointer using vut_ErrorGetObject.

Table of Contents , Error

NAME

vut_ErrorGetObject - get pointer to the current error object

C SPECIFICATION

void vut_ErrorGetObject (Vobject **object)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

object       Pointer to user defined object

DESCRIPTION

Query for the current user defined object pointer. Install a pointer to a user defined error object using vut_ErrorSetObject.

Table of Contents , Error

NAME

vut_ErrorString - return a descriptive error string

C SPECIFICATION

Vchar *vut_ErrorString (Vint errorflag)

INPUT ARGUMENTS

errorflag    Error flag

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the descriptive string associated with the error flag, errorflag.

DESCRIPTION

Return a pointer to a descriptive error string associated with the error flag, errorflag. If errorflag is not a valid error flag, then NULL is returned. Do not attempt to free the string returned by this function.

Table of Contents

3.3 Memory System - Memory

Like the Error module, the Memory module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the Memory module represents a single system wide data structure which is used by all DevTools objects and perhaps user code when managing memory resources.

By default, DevTools performs all memory management through the C language system functions malloc, realloc and free. Each of these three basic memory functions is wrapped by a Memory module function with an identical prototype. DevTools modules then access the underlying malloc, realloc and free system functions through these wrapper functions. The user may install replacements for the basic malloc, realloc and free functions called within the Memory module if desired.

If the Memory module is compiled using VKI_CHECK_MEM, then the memory system perform memory protection and checking functions. In addtion, if the Memory module is compiled using VKI_CHECK_MEMSTATS, the memory system will compute memory statistics which the user may query. These features are only available if user has not installed functions for malloc, realloc and free.

The Memory module supports the following functions.

Use vut_MemorySetFunctions to install user defined basic memory functions. The functions vut_MemoryMalloc, vut_MemoryRealloc and vut_MemoryFree invoke the current basic memory functions. Use vut_MemoryStatistics to return the current memory management statistics.

Table of Contents

3.4 Function Descriptions

The currently available Memory functions are described in detail in this section.

Table of Contents , Memory

NAME

vut_MemoryFree,vut_MemoryMalloc,vut_MemoryRealloc - call memory functions

C SPECIFICATION

void vut_MemoryFree (void *ptr)

void *vut_MemoryMalloc (size_t bytes)

void *vut_MemoryRealloc (void *ptr, size_t bytes)

INPUT ARGUMENTS

ptr          Pointer to memory to be freed or realloced
bytes        Number of bytes of memory to allocate

OUTPUT ARGUMENTS

None

DESCRIPTION

These functions call the basic C language free, malloc and realloc C language library functions or user defined free, realloc and malloc functions installed using vut_MemorySetFunctions.

Table of Contents , Memory

NAME

vut_MemorySetFunctions - install malloc, realloc and free functions

C SPECIFICATION

void vut_MemorySetFunctions (void*(*mallocfun)(size_t),
                             void*(*reallocfun)(void*, size_t),
                             void(*freefun)(void*))

INPUT ARGUMENTS

mallocfun    Pointer to malloc function
reallocfun   Pointer to realloc function
freefun      Pointer to free function

OUTPUT ARGUMENTS

None

DESCRIPTION

Install a pointer to user defined malloc, realloc and free memory functions. If a NULL pointer is passed for a particular function, the default function is installed. By default the C language library functions malloc, realloc and free are installed.

Table of Contents , Memory

NAME

vut_MemoryStatistics - query for memory system statistics

C SPECIFICATION

void vut_MemoryStatistics (size_t *cursize,
                           size_t *maxsize,
                           Vint *nummalloc,
                           Vint *numrealloc,
                           Vint *numfree)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

cursize      Current memory allocated in bytes.
maxsize      Maximum memory allocated in bytes.
nummalloc    Number of vut_MemoryMalloc calls
numrealloc   Number of vut_MemoryRealloc calls
numfree      Number of vut_MemoryFree calls

DESCRIPTION

Return memory management statistics. These statistics will be returned as zeros if not compiled with VKI_CHECK_MEM and VKI_CHECK_MEMSTATS

Table of Contents

3.5 Standard Output - Print

Like the Error module, the Print module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the Print module manages a single system wide data file descriptor which is used by all DevTools objects for directing printing to the console.

By default, the file descriptor (type FILE*), used by DevTools is stdout. The user may install an alternative file descriptor if desired. This is useful when building Microsoft Windows applications in which a console does not exist by default.

The Print module supports the following functions.

Table of Contents

3.6 Function Descriptions

The currently available Print functions are described in detail in this section.

Table of Contents , Print

NAME

vut_PrintSetFile - install printing file descriptor

C SPECIFICATION

void vut_PrintSetFile (FILE* fd)

INPUT ARGUMENTS

fd           Print to file descriptor

OUTPUT ARGUMENTS

None

DESCRIPTION

Install a file descriptor which will be used for all printing in DevTools. If a fd NULL pointer is passed, the default file descriptor is installed. By default the C language library file descriptor stdout is installed.

Table of Contents , Print

NAME

vut_PrintSetPath - install printing file path

C SPECIFICATION

void vut_PrintSetPath (Vchar* path)

INPUT ARGUMENTS

path         Print to file path

OUTPUT ARGUMENTS

None

DESCRIPTION

Install a file descriptor associated with path which will be used for all printing in DevTools. If path is not NULL, a file descriptor to the path name will be opened and installed. If a path NULL pointer is passed, the current file descriptor is closed and the default file descriptor is installed. By default the C language library file descriptor stdout is installed.

Table of Contents

3.7 Quadruple Precision - VQuad

Like the Error module, the VQuad module is not an object module in the sense that it supports the instancing of multiple objects. Instead, the VQuad module comprises a set of functions that operate on 128-bit quadruple-precision floating-point variables.

Quadruple precision variables are declared with the Vquad data type. Operators such as +, -, *, etc. are not defined for this data type. Instead, all operations are performed via VQuad functions.

The VQuad module supports the following functions.

Table of Contents

3.8 Function Descriptions

The currently available VQuad functions are described in detail in this section.

Table of Contents , VQuad

NAME

vut_VQuadSPrintf - prints variable to a string

C SPECIFICATION

void vut_VQuadSPrintf (Vquad f,
                       Vint width,
                       Vint sign,
                       Vchar buf[],
                       Vint *ierr)

INPUT ARGUMENTS

f            Quadruple precision variable to be printed
width        Width of output field
sign         Flag for printed positive sign
buf          The output string

OUTPUT ARGUMENTS

ierr         Error, if any

DESCRIPTION

Prints the value of the quadruple precision variable f onto the string buf. width and sign are borrowed from the C language. They describe the total field's width and whether to print a + sign for positive numbers, respectively.

If width is less than 9 or if an arithmetic error occurs during the print operation then ierr is set to 1. Otherwise it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadPrintf - prints variable to console

C SPECIFICATION

void vut_VQuadPrintf (Vquad f,
                      Vint width,
                      Vint sign,
                      Vint *ierr)

INPUT ARGUMENTS

f            Quadruple precision variable to be printed
width        Width of output field
sign         Flag for printed positive sign

OUTPUT ARGUMENTS

ierr         Error, if any

DESCRIPTION

Same as vut_VQuadSPrintf except that rather than a string the output goes to the console. Console output can be redirected using the Print module.

Table of Contents , VQuad

NAME

vut_VQuadLoad - loads a Vdouble into a Vquad

C SPECIFICATION

Vquad vut_VQuadLoad (Vdouble a)

INPUT ARGUMENTS

a            Double precision variable to be loaded

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is the loaded quadruple precision variable

DESCRIPTION

Casts a double precision floating point number into a quadruple precision variable. Since a double precision variable can always be written in quadruple precision this operation is always successful.

Table of Contents , VQuad

NAME

vut_VQuadStore - stores a Vquad into a Vdouble

C SPECIFICATION

Vdouble vut_VQuadStore (Vquad a,
                        Vint  *ierr)

INPUT ARGUMENTS

a            Quadruple precision variable to be stored

OUTPUT ARGUMENTS

ierr         Error, if any

FUNCTION RETURN VALUE

The function value is the stored double precision variable

DESCRIPTION

Casts a quadruple precision floating point number into a double precision variable. If the quadruple precision variable is too large such that the double precision variable would overflow ierr is set to 1. Otherwise it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadEQ - checks for Vquad a == Vquad b

C SPECIFICATION

Vint    vut_VQuadEQ (Vquad a,
                     Vquad b)

INPUT ARGUMENTS

a            First number to compare
b            Second number to compare

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is set to 1 if a and b are equal and to 0 otherwise.

DESCRIPTION

Checks for equality two quadruple precision numbers a and b.

Table of Contents , VQuad

NAME

vut_VQuadGE - checks for Vquad a >= Vquad b

C SPECIFICATION

Vint    vut_VQuadGE (Vquad a,
                     Vquad b)

INPUT ARGUMENTS

a            First number to compare
b            Second number to compare

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is set to 1 if a is greater than or equal to b and to 0 otherwise.

DESCRIPTION

Checks whether a is greater to or equal to b.

Table of Contents , VQuad

NAME

vut_VQuadGT - checks for Vquad a > Vquad b

C SPECIFICATION

Vint    vut_VQuadGT (Vquad a,
                     Vquad b)

INPUT ARGUMENTS

a            First number to compare
b            Second number to compare

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is set to 1 if a is greater than b and to 0 otherwise.

DESCRIPTION

Checks whether a is greater than b.

Table of Contents , VQuad

NAME

vut_VQuadLE - checks for Vquad a <= Vquad b

C SPECIFICATION

Vint    vut_VQuadLE (Vquad a,
                     Vquad b)

INPUT ARGUMENTS

a            First number to compare
b            Second number to compare

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is set to 1 if a is less than or equal to b and to 0 otherwise.

DESCRIPTION

Checks whether a is less than or equal to b.

Table of Contents , VQuad

NAME

vut_VQuadLT - checks for Vquad a < Vquad b

C SPECIFICATION

Vint    vut_VQuadGT (Vquad a,
                     Vquad b)

INPUT ARGUMENTS

a            First number to compare
b            Second number to compare

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is set to 1 if a is less than b and to 0 otherwise.

DESCRIPTION

Checks whether a is less than b

Table of Contents , VQuad

NAME

vut_VQuadAbs - performs ABS(Vquad a)

C SPECIFICATION

Vquad    vut_VQuadAbs (Vquad a)

INPUT ARGUMENTS

a        Number whose absolute value is required

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is set to the quadruple precision number that is the absolute value of a.

DESCRIPTION

Takes the absolute value of a quadruple precision number.

Table of Contents , VQuad

NAME

vut_VQuadAdd - performs Vquad a + Vquad b

C SPECIFICATION

Vquad    vut_VQuadAdd (Vquad a,
                       Vquad b,
                       Vint  *ierr)

INPUT ARGUMENTS

a        First number to be added
b        Second number to be added

OUTPUT ARGUMENTS

ierr     Error, if any

FUNCTION RETURN VALUE

The function value is set to the quadruple precision number that is the sum of a and b.

DESCRIPTION

Adds two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadDiv - performs Vquad a / Vquad b

C SPECIFICATION

Vquad    vut_VQuadDiv (Vquad a,
                       Vquad b,
                       Vint *ierr)

INPUT ARGUMENTS

a        Numerator
b        Denominator

OUTPUT ARGUMENTS

ierr     Error, if any

FUNCTION RETURN VALUE

The function value is set to the quadruple precision number that is the division of a by b.

DESCRIPTION

Divides two quadruple precision numbers. If the result overflows or if the denominator is zero then ierr is set to 1. Otherwise, it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadHalf - performs (Vquad a)/2

C SPECIFICATION

Vquad    vut_VQuadHalf (Vquad a)

INPUT ARGUMENTS

a        Number whose half is requested

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is set to the quadruple precision number that is half of a.

DESCRIPTION

Divides a quadruple precision number by 2.

Table of Contents , VQuad

NAME

vut_VQuadMult - performs Vquad a * Vquad b

C SPECIFICATION

Vquad    vut_VQuadMult (Vquad a,
                        Vquad b,
                        Vint *ierr)

INPUT ARGUMENTS

a        First multiplier
b        Second multiplier

OUTPUT ARGUMENTS

ierr     Error, if any

FUNCTION RETURN VALUE

The function value is set to the quadruple precision number that is the product of a and b.

DESCRIPTION

Multiplies two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadNeg - performs -(Vquad a)

C SPECIFICATION

Vquad    vut_VQuadNeg (Vquad a)

INPUT ARGUMENTS

a        Number whose negative is needed

OUTPUT ARGUMENTS

None

FUNCTION RETURN VALUE

The function value is set to the negative of quadruple precision number a provided.

DESCRIPTION

Takes the negative of a quadruple precision number.

Table of Contents , VQuad

NAME

vut_VQuadSqrt - performs sqrt(Vquad a)

C SPECIFICATION

Vquad    vut_VQuadSqrt (Vquad a,
                        Vint *ierr)

INPUT ARGUMENTS

a        Number whose square root is needed

OUTPUT ARGUMENTS

ierr       Error, if any

FUNCTION RETURN VALUE

The function value is set to the square root of the quadruple precision number a provided.

DESCRIPTION

Takes the square root of a quadruple precision number. If a is negative ierr is set to 1. Otherwise it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadSub - performs Vquad a - Vquad b

C SPECIFICATION

Vquad    vut_VQuadSub (Vquad a,
                       Vquad b,
                       Vint  *ierr)

INPUT ARGUMENTS

a        Number to be added
b        Number to be subtracted

OUTPUT ARGUMENTS

ierr     Error, if any

FUNCTION RETURN VALUE

The function value is set to the quadruple precision number that is the sum of a and b.

DESCRIPTION

Subtracts two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadCross3 - cross product of two 3-vectors

C SPECIFICATION

void    vut_VQuadCross3 (Vquad a[3],
                         Vquad b[3],
                         Vquad c[3],
                         Vint *ierr)

INPUT ARGUMENTS

a        First vector
b        Second vector

OUTPUT ARGUMENTS

c        Cross product of a and b.
ierr     Error, if any

DESCRIPTION

Takes the cross product of vectors a and b. If any component of the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadDot3 - dot product of two 3-vectors

C SPECIFICATION

Vquad    vut_VQuadDot3 (Vquad a[3],
                        Vquad b[3],
                        Vint *ierr)

INPUT ARGUMENTS

a        First vector
b        Second vector

OUTPUT ARGUMENTS

ierr     Error, if any

FUNCTION RETURN VALUE

The function value is set to the quadruple precision number that is the dot product between vectors a and b.

DESCRIPTION

Takes the dot product of vectors a and b. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadMag3 - computes the magnitude of a 3-vector

C SPECIFICATION

Vquad    vut_VQuadMag3 (Vquad a[3],
                        Vint *ierr)

INPUT ARGUMENTS

a        Vector whose magnitude is required

OUTPUT ARGUMENTS

ierr     Error, if any

FUNCTION RETURN VALUE

The function value is set to the quadruple precision number that is the magnitude of vector a.

DESCRIPTION

Computes the magnitude of vector a. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadScale3 - scales a 3-vector

C SPECIFICATION

void     vut_VQuadScale3 (Vquad a[3],
                          Vquad s,
                          Vquad b[3],
                          Vint  *ierr)

INPUT ARGUMENTS

a        Vector to be scaled
s        Scalar value

OUTPUT ARGUMENTS

b        The scaled vector
ierr     Error, if any

DESCRIPTION

Scales vector a by the scalar s. If any component of b overflows then ierr is set to 1. Otherwise, it is set to 0.

Table of Contents , VQuad

NAME

vut_VQuadUnit3 - scales a 3-vector to a unit 3-vector

C SPECIFICATION

void     vut_VQuadUnit3 (Vquad a[3],
                         Vquad b[3],
                         Vint  *ierr)

INPUT ARGUMENTS

a        Vector whose unit is requested

OUTPUT ARGUMENTS

b        Resulting unit vector
ierr     Error, if any

DESCRIPTION

Scales vector a into a unit vector. If any component of b overflows then ierr is set to 1. Otherwise, it is set to 0.