3. Error Handling, Memory System, Standard Output, Quadruple Precision - Error, Memory, Print, VQuad
CEETRON SAM 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 CEETRON SAM 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 CEETRON SAM 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 CEETRON SAM 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
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 CEETRON SAM objects and perhaps user code when calling an error handler. Functions exist to install a user defined error handler or a default CEETRON SAM 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.
Functions
vut_ErrorCall()
- call installed error handlervut_ErrorHandler()
- default error handlervut_ErrorSetHandler()
- install a pointer to the error handlervut_ErrorGetHandler()
- query pointer to the current error handlervut_ErrorSetObject()
- set a pointer to the error objectvut_ErrorGetObject()
- get pointer to the current error objectvut_ErrorString()
- return a descriptive error string
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 CEETRON SAM 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.
3.2. Function Descriptions
The currently available Error functions are described in detail in this section.
-
void vut_ErrorSetHandler(void (*func)(const Vchar*, Vint, const Vchar*))
install a pointer to the error handler
Install a pointer to a user defined error handler function. If a NULL pointer is passed, the default function
vut_ErrorHandler()
is installed. Please seevut_ErrorHandler()
for a description of the arguments to the error handler.- Parameters
func – Pointer to error handler
-
void vut_ErrorGetHandler(void (**func)(const Vchar*, Vint, const Vchar*))
query pointer to the current error handler
Query for the pointer to the current error handler function. Set a user defined error handler using
vut_ErrorSetHandler()
.- Parameters
func – [out] Pointer to error handler
-
void vut_ErrorSetObject(Vobject *object)
set a pointer to the error object
Install a pointer to a user defined error object. Query for the current user defined object pointer using
vut_ErrorGetObject()
.- Parameters
object – Pointer to user defined object
-
void vut_ErrorGetObject(Vobject **object)
get pointer to the current error object
Query for the current user defined object pointer. Install a pointer to a user defined error object using
vut_ErrorSetObject()
.- Parameters
object – [out] Pointer to user defined object
-
void vut_ErrorCall(const Vchar *funcname, Vint errorflag, const Vchar *message)
call installed error handler
The function passes the input arguments to the installed error handler.
To invoke the default error handler directly call
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 functionvoid vut_ErrorHandler (const Vchar *funcname, Vint errorflag, const Vchar *message)
vut_PrintSetFile()
. If the message string is a NULL or an empty string, then the descriptive error string is printed.- Parameters
funcname – Name of calling function
errorflag – Error flag
message – Message string
-
Vchar *vut_ErrorString(Vint errorflag)
return a descriptive error string
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.
- Parameters
errorflag – Error flag
- Returns
The function returns a pointer to the descriptive string associated with the error flag, errorflag.
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 CEETRON SAM objects and perhaps user code when managing memory resources.
By default, CEETRON SAM 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. CEETRON SAM 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.
Functions
vut_MemoryFree()
- call free functionvut_MemoryMalloc()
- call malloc functionvut_MemoryRealloc()
- call realloc functionvut_MemorySetFunctions()
- install malloc, realloc and free functionsvut_MemoryStatistics()
- query for memory system statistics
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.
3.4. Function Descriptions
The currently available Memory functions are described in detail in this section.
-
void vut_MemorySetFunctions(void *(*mfun)(size_t), void *(*rfun)(void*, size_t), void (*ffun)(void*))
install malloc, realloc and free functions
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.
- Parameters
mfun – Pointer to malloc function
rfun – Pointer to realloc function
ffun – Pointer to free function
-
void vut_MemoryStatistics(size_t *cursize, size_t *msize, Vint *nmalloc, Vint *nrealloc, Vint *nfree)
query for memory system statistics
Return memory management statistics. These statistics will be returned as zeros if not compiled with
VKI_CHECK_MEM
andVKI_CHECK_MEMSTATS
- Parameters
cursize – [out] Current memory allocated in bytes.
msize – [out] Maximum memory allocated in bytes.
nmalloc – [out] Number of vut_MemoryMalloc calls
nrealloc – [out] Number of vut_MemoryRealloc calls
nfree – [out] Number of vut_MemoryFree calls
-
void *vut_MemoryMalloc(size_t bytes)
call memory functions
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()
.- Parameters
bytes – Number of bytes of memory to allocate
-
void *vut_MemoryRealloc(void *ptr, size_t bytes)
call memory functions
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()
.- Parameters
ptr – Pointer to memory to be freed or realloced
bytes – Number of bytes of memory to allocate
-
void vut_MemoryFree(void *ptr)
call memory functions
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()
.
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 CEETRON SAM objects for directing printing to the console.
By default, the file descriptor (type FILE*), used by CEETRON SAM 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.
Functions
vut_PrintSetFile()
- install printing file descriptorvut_PrintSetPath()
- install printing file path
3.6. Function Descriptions
The currently available Print functions are described in detail in this section.
-
void vut_PrintSetFile(FILE *fd)
install printing file descriptor
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.
- Parameters
fd – Print to file descriptor
-
void vut_PrintSetPath(Vchar *path)
install printing file path
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.
- Parameters
path – Print to file path
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.
Printing functions
vut_VQuadSPrintf()
- prints variable to a stringvut_VQuadPrintf()
- prints variable to console
Load and store functions
vut_VQuadLoad()
- loads a Vdouble into a Vquadvut_VQuadStore()
- stores a Vquad into a Vdouble
Comparison functions
vut_VQuadEQ()
- checks for Vquad a == Vquad bvut_VQuadGE()
- checks for Vquad a >= Vquad bvut_VQuadGT()
- checks for Vquad a > Vquad bvut_VQuadLE()
- checks for Vquad a <= Vquad bvut_VQuadLT()
- checks for Vquad a < Vquad b
Arithmetic operations
vut_VQuadAbs()
- performs ABS(Vquad a)vut_VQuadAdd()
- performs Vquad a + Vquad bvut_VQuadDiv()
- performs Vquad a / Vquad bvut_VQuadHalf()
- performs (Vquad a)/2vut_VQuadMult()
- performs Vquad a * Vquad bvut_VQuadNeg()
- performs -(Vquad a)vut_VQuadSqrt()
- performs sqrt(Vquad a)vut_VQuadSub()
- performs Vquad a - Vquad b
Vector operations
vut_VQuadCross3()
- cross product of two 3-vectorsvut_VQuadDot3()
- dot product of two 3-vectorsvut_VQuadMag3()
- computes the magnitude of a 3-vectorvut_VQuadScale3()
- scales a 3-vectorvut_VQuadUnit3()
- scales a 3-vector to a unit 3-vector
3.8. Function Descriptions
The currently available VQuad functions are described in detail in this section.
-
void vut_VQuadPrintf(Vquad f, Vint width, Vint sign, Vint *ierr)
prints variable to console
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.- Parameters
f – Quadruple precision variable to be printed
width – Width of output field
sign – Flag for printed positive sign
ierr – [out] Error, if any
-
void vut_VQuadSPrintf(Vquad f, Vint width, Vint sign, Vchar buf[], Vint *ierr)
prints variable to a string
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.
- Parameters
f – Quadruple precision variable to be printed
width – Width of output field
sign – Flag for printed positive sign
buf – The output string
ierr – [out] Error, if any
-
Vquad vut_VQuadLoad(Vdouble a)
loads a Vdouble into a Vquad
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.
- Parameters
a – Double precision variable to be loaded
- Returns
The function value is the loaded quadruple precision variable
-
Vdouble vut_VQuadStore(Vquad a, Vint *ierr)
stores a Vquad into a Vdouble
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.
- Parameters
a – Quadruple precision variable to be stored
ierr – [out] Error, if any
- Returns
The function value is the stored double precision variable
-
Vint vut_VQuadEQ(Vquad a, Vquad b)
checks for Vquad a == Vquad b
Checks for equality two quadruple precision numbers a and b.
- Parameters
a – First number to compare
b – Second number to compare
- Returns
The function value is set to 1 if a and b are equal and to 0 otherwise.
-
Vint vut_VQuadGT(Vquad a, Vquad b)
checks for Vquad a > Vquad b
Checks whether a is greater than b.
- Parameters
a – First number to compare
b – Second number to compare
- Returns
The function value is set to 1 if a is greater than b and to 0 otherwise.
-
Vint vut_VQuadGE(Vquad a, Vquad b)
checks for Vquad a >= Vquad b
Checks whether a is greater to or equal to b.
- Parameters
a – First number to compare
b – Second number to compare
- Returns
The function value is set to 1 if a is greater than or equal to b and to 0 otherwise.
-
Vint vut_VQuadLT(Vquad a, Vquad b)
checks for Vquad a < Vquad b
Checks whether a is less than b
- Parameters
a – First number to compare
b – Second number to compare
- Returns
The function value is set to 1 if a is less than b and to 0 otherwise.
-
Vint vut_VQuadLE(Vquad a, Vquad b)
checks for Vquad a <= Vquad b
Checks whether a is less than or equal to b.
- Parameters
a – First number to compare
b – Second number to compare
- Returns
The function value is set to 1 if a is less than or equal to b and to 0 otherwise.
-
Vquad vut_VQuadAdd(Vquad a, Vquad b, Vint *ierr)
performs Vquad a + Vquad b
Adds two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.
- Parameters
a – First number to be added
b – Second number to be added
ierr – Error, if any
- Returns
The function value is set to the quadruple precision number that is the sum of a and b.
-
Vquad vut_VQuadSub(Vquad a, Vquad b, Vint *ierr)
performs Vquad a - Vquad b
Subtracts two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.
- Parameters
a – Number to be added
b – Number to be subtracted
ierr – [out] Error, if any
- Returns
The function value is set to the quadruple precision number that is the sum of a and b.
-
Vquad vut_VQuadMult(Vquad a, Vquad b, Vint *ierr)
performs Vquad a * Vquad b
Multiplies two quadruple precision numbers. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.
- Parameters
a – First multiplier
b – Second multiplier
ierr – [out] Error, if any
- Returns
The function value is set to the quadruple precision number that is the product of a and b.
-
Vquad vut_VQuadDiv(Vquad a, Vquad b, Vint *ierr)
performs Vquad a / Vquad b
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.
- Parameters
a – Numerator
b – Denominator
ierr – [out] Error, if any
- Returns
The function value is set to the quadruple precision number that is the division of a by b.
-
Vquad vut_VQuadSqrt(Vquad a, Vint *ierr)
performs sqrt(Vquad a)
Takes the square root of a quadruple precision number. If a is negative ierr is set to 1. Otherwise it is set to 0.
- Parameters
a – Number whose square root is needed
ierr – [out] Error, if any
- Returns
The function value is set to the square root of the quadruple precision number a provided.
-
Vquad vut_VQuadHalf(Vquad a)
performs (Vquad a)/2
Divides a quadruple precision number by 2.
- Parameters
a – Number whose half is requested
- Returns
The function value is set to the quadruple precision number that is half of a.
-
Vquad vut_VQuadNeg(Vquad a)
checks for Vquad a <= Vquad b
Takes the negative of a quadruple precision number.
- Parameters
a – Number whose negative is needed
- Returns
The function value is set to the negative of quadruple precision number a provided.
-
Vquad vut_VQuadDot3(Vquad a[3], Vquad b[3], Vint *ierr)
dot product of two 3-vectors
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.
- Parameters
a – First vector
b – Second vector
ierr – [out] Error, if any
- Returns
The function value is set to the quadruple precision number that is the dot product between vectors a and b.
-
void vut_VQuadCross3(Vquad a[3], Vquad b[3], Vquad c[3], Vint *ierr)
cross product of two 3-vectors
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.
- Parameters
a – First vector
b – Second vector
c – [out] Cross product of a and b.
ierr – [out] Error, if any
-
void vut_VQuadScale3(Vquad a[3], Vquad s, Vquad b[3], Vint *ierr)
scales a 3-vector
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.
- Parameters
a – Vector to be scaled
s – Scalar value
b – [out] The scaled vector
ierr – [out] Error, if any
-
Vquad vut_VQuadMag3(Vquad a[3], Vint *ierr)
computes the magnitude of a 3-vector
Computes the magnitude of vector a. If the result overflows then ierr is set to 1. Otherwise, it is set to 0.
- Parameters
a – Vector whose magnitude is required
ierr – [out] Error, if any
- Returns
The function value is set to the quadruple precision number that is the magnitude of vector a.
-
void vut_VQuadUnit3(Vquad a[3], Vint *ierr)
scales a 3-vector to a unit 3-vector
Scales vector a into a unit vector.
- Parameters
a – [inout] Vector whose unit is requested
ierr – [out] Error, if any
-
Vquad vut_VQuadAbs(Vquad a)
performs ABS(Vquad a)
Takes the absolute value of a quadruple precision number.
- Parameters
a – Number whose absolute value is required
- Returns
The function value is set to the quadruple precision number that is the absolute value of a.