NAME

C SPECIFICATION

#include <cx/DataOps.h>

typedef enum {
 cx_check_magic
 cx_check_mem_bounds
} cxDataCheckLevel;

typedef enum {
 cx_check_ignore
 cx_check_warning
 cx_check_halt
 cx_check_abort
 cx_check_callback
} cxDataCheckAction;

typedef void (*cxDataCheckCallback)( cxDataCheckErrorInfo*, void* );

void cxDataCheckingSet( cxDataCheckLevel level,
   cxDataCheckAction action,
   cxDataCheckCallback callback );

FORTRAN SPECIFICATION

integer cx_check_magic
integer cx_check_mem_bounds

parameter (cx_check_magic  = 0)
parameter (cx_check_mem_bounds = 1)

integer cx_check_ignore
integer cx_check_warning
integer cx_check_halt
integer cx_check_abort
integer cx_check_callback

parameter (cx_check_ignore  = 0)
parameter (cx_check_warning = 1)
parameter (cx_check_halt  = 2)
parameter (cx_check_abort  = 3)
parameter (cx_check_callback = 4)

typedef void (*cxDataCheckCallback)( cxDataCheckError, void* );

subroutine cxDataCheckingSet( level, action, callback )
integer level
integer action
integer callback

PARAMETERS

level

The level of detail of checking to be performed on data.

action

The action to be performed when an error in the data is detected.

callback

An optional routine that will be called when an error in the data is detected.

DESCRIPTION

cxDataCheckingSet defines the level of detail of the checking and what action is to be performed when an error is detected. Data is checked when it is stored in input or output ports, and whenever it is extracted from an input port by cxInputDataGet. The level parameter defines the amount of checking that is to be done.

cx_check_magic

the "magic number" field in the data is checked for validity. This helps detect operations on data that has already been reclaimed.

cx_check_mem_bounds

every array within a data type (e.g. the dims array in a cxLattice) is allocated with extra boundary "fenceposts" at the beginning and the end. Special byte sequences, and the size of the array in bytes are stored in the fenceposts. This helps detect memory indexing and allocation errors.

The action parameter defines the action to be taken when an error is detected.

cx_check_ignore

operations which might cause the module to fail are avoided, but the error is not reported.

cx_check_warning

the error is reported to the user by a simple text message.

cx_check_halt

the error is reported to the user and the module sleeps, allowing the user to examine the process with a debugger. The module sleeps as long as the external integer cxDataErrorRelease is false, so the halted module can be released by using the debugger to set this variable to a non-zero value.

cx_check_abort

the error is reported to the user and the module aborts. Any data referenced by the module is not reclaimed, and will be leaked.

cx_check_callback

the user supplied callback routine, callback is called, with the cxDataCheckErrorInfo structure and the pointer to the data containing the error. This allows the user to customize handling and reporting of errors.

The default action is for magic numbers to be checked on all data reference count changes and a warning to be issued. Magic number checking is always performed to prevent a module from attempting to lock a the reference count of data that has been damaged, which would inadvertently (and permanently) lock all modules out of the data arena. The level parameter values are listed in order of strictness, and each subsequent value implies that the lower level test is also done. That is, the magic number is always checked before the memory bounds.

The cxDataCheckCallback routines cxDataWarning, cxDataHalt, and cxDataAbort implement the cx_check_warning, cx_check_halt, and cx_check_abort actions. They are defined publicly so the user may access them directly. For example, the default actions can be restored by the following call:

cxDataCheckingSet( cx_check_magic,


cx_check_ref,
cxDataCheckCallback,
cxDataWarning );

SEE ALSO