module xdc.runtime.Error

Runtime error manager

The Error module provides mechanisms for raising, checking, and handling errors in a program. At the configuration time, you can use the parameters Error.policy, Error.policyFxn and Error.raiseHook to specify what happens when an error takes place. You can control how much debugging information is available in that case, while also controlling the memory footprint that the `Error' module adds to the program. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Error.xdc
#include <xdc/runtime/Error.h>
Functions
Bool 
UInt16 
CString 
Void 
Void 
Error_policyDefault// Default implementation of the policyFxn(Error_Block *eb, Types_ModuleId mod, CString file, Int line, Error_Id id, IArg arg1, IArg arg2);
Void 
Void 
Error_policySpin// Lightweight implementation of the policyFxn(Error_Block *eb, Types_ModuleId mod, CString file, Int line, Error_Id id, IArg arg1, IArg arg2);
Void 
macro Void 
Error_raise// Raise an error(Error_Block *eb, Error_Id id, IArg arg1, IArg arg2);
Functions common to all target modules
Defines
extern const Error_Block 
extern const Error_Block 
#define
Typedefs
typedef struct
typedef struct
typedef Void 
typedef opaque
typedef enum
typedef Void 
Constants
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const UInt16 
extern const Error_Policy 
extern const Error_PolicyFxn 
extern const Error_HookFxn 
 
DETAILS
The Error module provides mechanisms for raising, checking, and handling errors in a program. At the configuration time, you can use the parameters Error.policy, Error.policyFxn and Error.raiseHook to specify what happens when an error takes place. You can control how much debugging information is available in that case, while also controlling the memory footprint that the `Error' module adds to the program.
Module producers use this module to define specific error types and reference these when raising an error. Each error type has a custom error message and can be parameterized with up to NUMARGS arguments. A generic error type is provided for raising errors when not in a module.
Use the Error_check() function in your application or module to determine if an error has been raised in a function that takes an Error_Block as an argument. It is important to understand that it is the caller's responsibility to check the error block after calling such a function. Otherwise, a raised error may go undetected, which could compromise the integrity of the system. For example:
  Task_create(..., &eb);

  if (Error_check(&eb)) {
      ...an error has been raised...
  }
The function assigned to the parameter Error.policyFxn is the central part of the error handling mechanism in this module. Most of the users will either leave this parameter at its default value, or select one of the alternative implementations that are included with the Error module. However, this configuration parameter also allows users to completely take over the error handling by setting this parameter to their own implementation. In that case, we recommend that users first review the included implementations, and base their implementation on one of these function. The included implementations are policyDefault, policyMin, and policySpin.
The Error.raiseHook configuration parameter allows a configured function to be invoked when an error is raised. This function is invoked from the default implementation of Error.policyFxn. Therefore, if a different implementation of Error.policyFxn is used, the function specified by Error.raiseHook may or may not be called. This function is passed a pointer to the error's error block and makes it easy to manage all errors from a common point. For example, you can trap any error (fatal or not) by simply setting a breakpoint in this function. You can use the following functions to extract information from an error block.
The Error module provides facilities for handling errors, but the Log module also provides features for logging error events. These are separate concepts; however, to ensure that users do not have to both raise and log an error, the Error module will automatically log an error event when one is raised. The Error module logs the standard Log.L_error event, passing it the error message and arguments.
The error event is logged to the Error module's logger using the Error module's diags mask. Logging of errors is enabled by default in the diags mask, but the event will not be logged unless a logger is configured for the Error module as well.
To make the error event appear as though it is coming from the module which called Error_raise, the event is logged with the caller's module id and with the caller's call site information.
EXAMPLES
Example 1: The following example shows how a module, named ModA, defines a custom error type and shows how this error is raised by the module. The module defines an Id of E_notEven in its module specification file (in this case, ModA.xdc). The error's message string takes only one argument. The module also defines a mayFail() function that takes an error block. In the module's C source file, the function checks for the error condition and raises the error if needed.
This is part of ModA's XDC specification file for the module:
  config xdc.runtime.Error.Id E_notEven = {
      msg: "expected an even number (%d)"
  };

  Void mayFail(Int x, xdc.runtime.Error.Block *eb);
This is part of the C code for the module:
  Void ModA_mayFail(Int x, Error_Block *eb)
  {
      if ((x % 2) != 0) {
          Error_raise(eb, ModA_E_notEven, x, 0);
          ...add error handling code here...
          return;
      }
      ...
  }

Example 2: The following C code supplies an error block to a function that requires one and tests the error block to see if the function raised an error. Note that an error block must be initialized before it can be used and same error block may be passed to several functions.
  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/knl/Task.h>
  Error_Block eb;
  Task_Handle tsk;

  Error_init(&eb);
  tsk = Task_create(..., &eb);

  if (Error_check(&eb)) {
      ...an error has been raised...
  }

Example 3: The following C code shows that you may pass a special constant Error_ABORT in place of an error block to a function requiring an error block. In this case, if the function raises an error, the program is aborted (via xdc_runtime_System_abort()), thus execution control will never return to the caller.
  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/knl/Task.h>

  tsk = Task_create(..., Error_ABORT);
  ...will never get here if an error was raised in Task_create...

Example 4: The following C code shows that you may pass a special constant Error_IGNORE in place of an error block to a function requiring an error block. The purpose of this constant is to avoid allocating an error block on stack in the use case where the caller is not checking the error block after the call returns. In this example, the caller only checks the returned value but not the error block. If the function raises an error, the program will return to the caller, assuming Error_policy is set to UNWIND.
  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/knl/Task.h>

  tsk = Task_create(..., Error_IGNORE);
  if (tsk != NULL) {
      ...
  }

Example 5: The following C code shows how to write a function that is not part of a module and that takes an error block and raises the generic error type provided by the Error module. Note, if the caller passes Error_ABORT for the error block or if the error policy is TERMINATE, then the call to Error_raise() will call xdc_runtime_System_abort() and never return.
  #include <xdc/runtime/Error.h>

  Void myFunc(..., Error_Block *eb)
  {
      ...

      if (...error condition detected...) {
          String  myErrorMsg = "my custom error message";
          Error_raise(eb, Error_E_generic, myErrorMsg, 0);
          ...add error handling code here...
          return;
      }
  }
 
const Error_ABORT

A special Error_Block pointer that terminates the application in case of an error

C synopsis target-domain
extern const Error_Block Error_ABORT;
 
DETAILS
This constant has the same effect as passing NULL in place of an Error_Block. If an error is raised when Error_ABORT is passed, the application terminates regardless of Error_policy.
 
const Error_IGNORE

A pointer to a special Error_Block used when the caller does not want to check Error_Block

C synopsis target-domain
extern const Error_Block Error_IGNORE;
 
DETAILS
This constant should be used when the caller does not plan to check Error_Block after the call returns, but wants the call to return even in the case when an error is raised. Error_policy is still in effect and the application will still terminate when an error is raised if Error_policy is not set to Error_UNWIND.
 
const Error_NUMARGS

Maximum number of arguments supported by an error

C synopsis target-domain
#define Error_NUMARGS (Int)2
 
 
enum Error_Policy

Error handling policies

C synopsis target-domain
typedef enum Error_Policy {
    Error_TERMINATE,
    Error_UNWIND
} Error_Policy;
 
VALUES
TERMINATE — All raised errors are fatal. A call to Error_raise will never return to the caller. The program calls System_abort instead.
UNWIND — Errors are returned to the caller. A call to Error_raise will return back to the caller.
DETAILS
These constants are assigned to Error.policy to control the flow of the program when an error is raised.
 
typedef Error_HookFxn

Function called whenever an error is raised

C synopsis target-domain
typedef Void (*Error_HookFxn)(Error_Block*);
 
DETAILS
The first parameter and only parameter passed to this function is a pointer to an Error_Block. Even if the client passes a NULL error block pointer to Error_raise, this parameter passed to this "hook" function is always non-NULL.
 
typedef Error_Id

Error identifier

C synopsis target-domain
typedef opaque Error_Id;
 
DETAILS
Each type of error raised is defined with a metaonly Error.Desc. An Error_Id is a 32-bit target value that encodes the information in the Desc. Target programs use Error_Id values to "raise" and check for specific errors.
WARNING
Id values may vary among different configurations of an application. For example, the addition of a new module to a program may result in a different absolute value for E_generic. If you need error numbers that remain invariant, use the user definable Desc.code field.
 
typedef Error_PolicyFxn

Error policy function signature

C synopsis target-domain
typedef Void (*Error_PolicyFxn)(Error_Block*,Types_ModuleId,CString,Int,Error_Id,IArg,IArg);
 
PARAMETERS
A policy function is passed the following parameters:
eb
A pointer to an Error_Block structure to be initialized using the subsequent arguments. This pointer may be NULL.
modId
The module ID of the module calling Error_raise()
fileName
A string naming the source file which made the call to Error_raise()
lineNumber
An integer line number within the file named above where the call Error_raise() occured
errId
The Error_Id of the error being raised
arg1 and arg2
Two IArg arguments associated with the error being raised
 
struct Error_Block

Error block

C synopsis target-domain
typedef struct Error_Block Error_Block;
 
DETAILS
An opaque structure used to store information about errors once raised. This structure must be initialized via Error_init() before being used for the first time.
 
struct Error_Data

Error args

C synopsis target-domain
typedef struct Error_Data {
    IArg arg[Error_NUMARGS];
} Error_Data;
 
DETAILS
The two arguments (arg1, arg2) passed to raise are stored in one of these arrays within the associated Error_Block. To access these arguments use getData to obtain a pointer to the Error_Block's Data array.
SEE
 
config Error_E_generic  // module-wide

Generic error

C synopsis target-domain
extern const Error_Id Error_E_generic;
 
DETAILS
This error takes advantage of the $S specifier to allow for recursive formatting of the error message passed to error raise.
For example, the following is possible:
  Error_raise(eb, Error_E_generic, "Error occurred, code: %d", code);
SEE
 
config Error_E_memory  // module-wide

Out of memory error

C synopsis target-domain
extern const Error_Id Error_E_memory;
 
DETAILS
The first parameter must be the heap instance handle. The second parameter is the size of the object for which the allocation failed.
 
config Error_E_msgCode  // module-wide

Generic error that displays a string and a numeric value

C synopsis target-domain
extern const Error_Id Error_E_msgCode;
 
 
config Error_maxDepth  // module-wide

Maximum number of concurrent calls to raiseHook

C synopsis target-domain
extern const UInt16 Error_maxDepth;
 
DETAILS
To prevent errors that occur in the raiseHook function from causing an infinite recursion, the maximum number of concurrent calls to raiseHook is limited by Error_maxDepth. If the number of concurrent calls exceeds Error_maxDepth, the raiseHook function is not called.
In multi-threaded systems, errors raised by separate threads may be detected as recursive calls to raiseHook. So, setting Error.maxDepth to a small value may - in rare instances - result in errorHook not being called for some raised errors.
If it is important that all raised errors trigger a call to the raiseHook function, set Error.maxDepth to an impossibly large number (0xffff) and either ensure that the raise hook never calls a function that can raise an error or add checks in raiseHook to protect against "double faults".
 
config Error_policy  // module-wide

System-wide error handling policy

C synopsis target-domain
extern const Error_Policy Error_policy;
 
DETAILS
You can use this parameter to decide at the configuration time what happens when an error is raised. The program can either call System_abort() or return back to the caller. The implementations of Error.policyFxn should consider this parameter, but some implementations may not do so to save the memory footprint (Error_policySpin, for example).
 
config Error_policyFxn  // module-wide

Error handler function

C synopsis target-domain
extern const Error_PolicyFxn Error_policyFxn;
 
DETAILS
This function is called to handle all raised errors but, unlike raiseHook, this function is responsible for completely handling the error (including calling raiseHook with an appropriately initialized Error_Block, if raiseHook functionality is required).
The default value is a function which, in addition to calling raiseHook with an initialized Error_Block structure, logs the error using this module's logger.
Alternately, policySpin, which simply loops indefinitely, can be used to minimize target footprint. Note, this function does NOT call raiseHook, and also ignores Error.policy.
The third implementation, policyMin finds a middle ground between the two implementations above in terms of memory footprint and the available error information. Only the Error_Id of the error being raised is available in the resulting Error_Block, raiseHook is not invoked, but Error.policy is observed.
 
config Error_raiseHook  // module-wide

The function to call whenever an error is raised

C synopsis target-domain
extern const Error_HookFxn Error_raiseHook;
 
DETAILS
If set to a non-null value, the referenced function is always called when an error is raised, even if the Error policy is TERMINATE. In rare cases, it is possible that a raised error does not trigger a call to raiseHook; see maxDepth.
Regardless of the current policy in use, raising an error by calling Error_raise will always invoke the error raise hook function assigned to the Error.raiseHook configuration parameter, if the default Error.policyFxn implementation is used.
By default, this function is set to Error_print which causes the error to be formatted and output via System_printf. Setting this configuration parameter to null indicates that no function hook should be called.
SEE
 
Error_check()  // module-wide

Return TRUE if an error was raised

C synopsis target-domain
Bool Error_check(Error_Block *eb);
 
ARGUMENTS
eb — pointer to an Error_Block, Error_ABORT or Error_IGNORE
RETURNS
If eb is non-NULL and Error.policy == UNWIND and an error was raised on eb, this function returns TRUE. Otherwise, it returns FALSE.
 
Error_getCode()  // module-wide

Get an error's code

C synopsis target-domain
UInt16 Error_getCode(Error_Block *eb);
 
ARGUMENTS
eb — non-NULL pointer to an Error_Block
RETURNS
getCode returns the error code associated with this error block.
SEE
 
Error_getData()  // module-wide

Get an error's argument list

C synopsis target-domain
Error_Data *Error_getData(Error_Block *eb);
 
ARGUMENTS
eb — non-NULL pointer to an Error_Block
RETURNS
getData returns an array of type Data with NUMARGS elements containing the arguments provided at the time the error was raised.
SEE
 
Error_getId()  // module-wide

Get an error's id

C synopsis target-domain
Error_Id Error_getId(Error_Block *eb);
 
ARGUMENTS
eb — non-NULL pointer to an Error_Block
WARNING
Error_Id values may vary among different configurations of an application. For example, the addition of a new module to a program may result in a different absolute value for E_generic. If you need error numbers that remain invariant, use the user definable Desc.code field.
SEE
 
Error_getMsg()  // module-wide

Get an error's "printf" format string

C synopsis target-domain
CString Error_getMsg(Error_Block *eb);
 
ARGUMENTS
eb — non-NULL pointer to an Error_Block
SEE
 
Error_getSite()  // module-wide

Get an error's call site info

C synopsis target-domain
Types_Site *Error_getSite(Error_Block *eb);
 
ARGUMENTS
eb — non-NULL pointer to an Error_Block
RETURNS
getSite returns a pointer to an initialized Types.Site structure. However, in the event that the call site was compiled with xdc_FILE defined to be NULL (to minimize string space overhead) the file field may be set to NULL.
SEE
 
Error_init()  // module-wide

Put an error block into its initial state

C synopsis target-domain
Void Error_init(Error_Block *eb);
 
ARGUMENTS
eb — pointer to an Error_Block, Error_ABORT or Error_IGNORE
If eb is NULL this function simply returns.
DETAILS
To ensure reliable error detection, clients must call init for an Error_Block prior to any use.
If the same Error Block is used multiple times, only the last error raised is retained.
 
Error_policyDefault()  // module-wide

Default implementation of the policyFxn

C synopsis target-domain
Void Error_policyDefault(Error_Block *eb, Types_ModuleId mod, CString file, Int line, Error_Id id, IArg arg1, IArg arg2);
 
DETAILS
This function is the implementation which is plugged in by default to the policyFxn. It processes the error and logs it before returning to the caller or aborting - depending on the error policy policy.
 
Error_policyMin()  // module-wide

Implementation of the policyFxn with a smaller footprint

C synopsis target-domain
Void Error_policyMin(Error_Block *eb, Types_ModuleId mod, CString file, Int line, Error_Id id, IArg arg1, IArg arg2);
 
DETAILS
This function is a compromise between a debug-friendly policyDefault, which offers more details about any raised errors, but requires a larger footprint, and policySpin, which is small but does not display any debug information.
This function returns to the caller, unless policy is set to TERMINATE, or the Error_Block passed to it is NULL. If it returns, the only information available in the returned Error_Block is the error ID.
 
Error_policySpin()  // module-wide

Lightweight implementation of the policyFxn

C synopsis target-domain
Void Error_policySpin(Error_Block *eb, Types_ModuleId mod, CString file, Int line, Error_Id id, IArg arg1, IArg arg2);
 
DETAILS
This function is a lightweight alternative which can be plugged in to the policyFxn. It just loops infinitely.
WARNING
This function does not call raiseHook and never returns to the caller. As a result, ANY error raised by the application will cause it to indefinitly hang.
 
Error_print()  // module-wide

Print error using System.printf()

C synopsis target-domain
Void Error_print(Error_Block *eb);
 
ARGUMENTS
eb — pointer to an Error_Block, Error_ABORT or Error_IGNORE
If eb is Error_ABORT or Error_IGNORE, this function simply returns with no output.
DETAILS
This function prints the error using System_printf(). The output is on a single line terminated with a new line character and has the following form:
      <site>: <file>, line <line_num>: <err_msg>
where <site> is the module that raised the error, <file> and <line_num> are the file and line number of the containing the call site of the Error_raise(), and <err_msg> is the error message rendered with the arguments associated with the error.
WARNING
This function is not protected by a gate and, as a result, if two threads call this method concurrently, the output of the two calls will be intermingled. To prevent intermingled error output, you can either wrap all calls to this method with an appropriate Gate_enter/Gate_leave pair or simply ensure that only one thread in the system ever calls this method.
 
Error_raise()  // module-wide

Raise an error

C synopsis target-domain
macro Void Error_raise(Error_Block *eb, Error_Id id, IArg arg1, IArg arg2);
 
ARGUMENTS
eb — pointer to an Error_Block, Error_ABORT or Error_IGNORE
If eb is Error_ABORT or Error.policy == TERMINATE, this function does not return to the caller; after calling any configured raiseHook, System_abort is called with the string "xdc.runtime.Error.raise: terminating execution\n".
id — the error to raise
This pointer identifies the class of error being raised; the error class indicates how to interpret any subsequent arguments passed to raise.
arg1 — error's first argument
The argument interpreted by the first control character in the error message format string. It is ignored if not needed.
arg2 — error's second argument
The argument interpreted by the second control character in the error message format string. It is ignored if not needed.
DETAILS
This function is used to raise an Error by writing call site, error ID, and error argument information into the Error_Block pointed to by eb.
If Error_raise is called more than once on an Error_Block object, the previous error information is overwritten; only the last error is retained in the Error_Block object.
In all cases, any configured Error.raiseHook function is called with a non-NULL pointer to a fully initialized Error_Block object.
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId Error_Module_id();
// Get this module's unique id
 
Bool Error_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Error_Module_heap();
// The heap from which this module allocates memory
 
Bool Error_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Error_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Error_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in xdc/runtime/Error.xdc
var Error = xdc.useModule('xdc.runtime.Error');
module-wide constants & types
 
        const Error.TERMINATE;
        const Error.UNWIND;
 
    var obj = new Error.Data// Error args;
        obj.arg = IArg[Error.NUMARGS]  ...
 
    var obj = new Error.Desc// Error descriptor;
        obj.msg = String  ...
        obj.code = UInt16  ...
module-wide config parameters
        msg: "%$S"
    };
        msg: "out of memory: heap=0x%x, size=%u"
    };
        msg: "%s 0x%x"
    };
 
 
 
const Error.ABORT

A special Error_Block pointer that terminates the application in case of an error

Configuration settings
const Error.ABORT = ;
 
DETAILS
This constant has the same effect as passing NULL in place of an Error_Block. If an error is raised when Error_ABORT is passed, the application terminates regardless of Error_policy.
C SYNOPSIS
 
const Error.IGNORE

A pointer to a special Error_Block used when the caller does not want to check Error_Block

Configuration settings
const Error.IGNORE = ;
 
DETAILS
This constant should be used when the caller does not plan to check Error_Block after the call returns, but wants the call to return even in the case when an error is raised. Error_policy is still in effect and the application will still terminate when an error is raised if Error_policy is not set to Error_UNWIND.
C SYNOPSIS
 
const Error.NUMARGS

Maximum number of arguments supported by an error

Configuration settings
const Error.NUMARGS = 2;
 
C SYNOPSIS
 
enum Error.Policy

Error handling policies

Configuration settings
values of type Error.Policy
    const Error.TERMINATE;
    const Error.UNWIND;
 
VALUES
TERMINATE — All raised errors are fatal. A call to Error_raise will never return to the caller. The program calls System_abort instead.
UNWIND — Errors are returned to the caller. A call to Error_raise will return back to the caller.
DETAILS
These constants are assigned to Error.policy to control the flow of the program when an error is raised.
C SYNOPSIS
 
struct Error.Data

Error args

Configuration settings
var obj = new Error.Data;
 
    obj.arg = IArg[Error.NUMARGS]  ...
 
DETAILS
The two arguments (arg1, arg2) passed to raise are stored in one of these arrays within the associated Error_Block. To access these arguments use getData to obtain a pointer to the Error_Block's Data array.
SEE
C SYNOPSIS
 
metaonly struct Error.Desc

Error descriptor

Configuration settings
var obj = new Error.Desc;
 
    obj.msg = String  ...
    obj.code = UInt16  ...
 
FIELDS
msg — The error message using a printf style format string, but limited to NUMARGS arguments. This format string together with the two arguments passed to Error_raise` are used to create a human readable error message.
code — A user assignable code, 0 by default. The user may optionally set this field during config to give the error a well-known numeric code.
DETAILS
Each type of error is defined with an error descriptor. This structure groups common information about the errors of this type.
 
config Error.E_generic  // module-wide

Generic error

Configuration settings
Error.E_generic = Error.Desc {
    msg: "%$S"
};
 
DETAILS
This error takes advantage of the $S specifier to allow for recursive formatting of the error message passed to error raise.
For example, the following is possible:
  Error_raise(eb, Error_E_generic, "Error occurred, code: %d", code);
SEE
C SYNOPSIS
 
config Error.E_memory  // module-wide

Out of memory error

Configuration settings
Error.E_memory = Error.Desc {
    msg: "out of memory: heap=0x%x, size=%u"
};
 
DETAILS
The first parameter must be the heap instance handle. The second parameter is the size of the object for which the allocation failed.
C SYNOPSIS
 
config Error.E_msgCode  // module-wide

Generic error that displays a string and a numeric value

Configuration settings
Error.E_msgCode = Error.Desc {
    msg: "%s 0x%x"
};
 
C SYNOPSIS
 
config Error.maxDepth  // module-wide

Maximum number of concurrent calls to raiseHook

Configuration settings
Error.maxDepth = UInt16 16;
 
DETAILS
To prevent errors that occur in the raiseHook function from causing an infinite recursion, the maximum number of concurrent calls to raiseHook is limited by Error_maxDepth. If the number of concurrent calls exceeds Error_maxDepth, the raiseHook function is not called.
In multi-threaded systems, errors raised by separate threads may be detected as recursive calls to raiseHook. So, setting Error.maxDepth to a small value may - in rare instances - result in errorHook not being called for some raised errors.
If it is important that all raised errors trigger a call to the raiseHook function, set Error.maxDepth to an impossibly large number (0xffff) and either ensure that the raise hook never calls a function that can raise an error or add checks in raiseHook to protect against "double faults".
C SYNOPSIS
 
config Error.policy  // module-wide

System-wide error handling policy

Configuration settings
Error.policy = Error.Policy Error.UNWIND;
 
DETAILS
You can use this parameter to decide at the configuration time what happens when an error is raised. The program can either call System_abort() or return back to the caller. The implementations of Error.policyFxn should consider this parameter, but some implementations may not do so to save the memory footprint (Error_policySpin, for example).
C SYNOPSIS
 
config Error.policyFxn  // module-wide

Error handler function

Configuration settings
Error.policyFxn = Void(*)(Error.Block*,Types.ModuleId,CString,Int,Error.Id,IArg,IArg) Error.policyDefault;
 
DETAILS
This function is called to handle all raised errors but, unlike raiseHook, this function is responsible for completely handling the error (including calling raiseHook with an appropriately initialized Error_Block, if raiseHook functionality is required).
The default value is a function which, in addition to calling raiseHook with an initialized Error_Block structure, logs the error using this module's logger.
Alternately, policySpin, which simply loops indefinitely, can be used to minimize target footprint. Note, this function does NOT call raiseHook, and also ignores Error.policy.
The third implementation, policyMin finds a middle ground between the two implementations above in terms of memory footprint and the available error information. Only the Error_Id of the error being raised is available in the resulting Error_Block, raiseHook is not invoked, but Error.policy is observed.
C SYNOPSIS
 
config Error.raiseHook  // module-wide

The function to call whenever an error is raised

Configuration settings
Error.raiseHook = Void(*)(Error.Block*) Error.print;
 
DETAILS
If set to a non-null value, the referenced function is always called when an error is raised, even if the Error policy is TERMINATE. In rare cases, it is possible that a raised error does not trigger a call to raiseHook; see maxDepth.
Regardless of the current policy in use, raising an error by calling Error_raise will always invoke the error raise hook function assigned to the Error.raiseHook configuration parameter, if the default Error.policyFxn implementation is used.
By default, this function is set to Error_print which causes the error to be formatted and output via System_printf. Setting this configuration parameter to null indicates that no function hook should be called.
SEE
C SYNOPSIS
 
metaonly config Error.common$  // module-wide

Common module configuration parameters

Configuration settings
Error.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Thu, 23 May 2019 00:24:45 GMT