module xdc.runtime.Error

Runtime error manager

The Error module provides mechanisms for raising, checking, and handling errors in a program. You can configure it via the Error.policy and Error.raiseHook configuration parameters. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Error.xdc
#include <xdc/runtime/Error.h>
Functions
Bool 
UInt16 
String 
Void 
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
#define
Typedefs
typedef struct
typedef struct
typedef opaque
typedef enum
Constants
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const UInt16 
extern const Error_Policy 
extern const Void 
 
DETAILS
The Error module provides mechanisms for raising, checking, and handling errors in a program. You can configure it via the Error.policy and Error.raiseHook configuration parameters.
Modules may 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 to determine if an error has been raised. It is important to understand that it is the caller's responsibility to check the error block after calling a function that takes an error block as an argument. 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 Error.raiseHook configuration parameter allows a configured function to be invoked when any error is raised. 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 NULL 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(..., NULL);
  ...will never get here if an error was raised in Task_create...

Example 4: 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 NULL 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_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.
UNWIND — Errors are returned to the caller. A call to Error_raise will return back to the caller.
DETAILS
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.
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.
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;
config Error_raiseHook  // module-wide

The function to call whenever an error is raised

C synopsis target-domain
extern const Void (*Error_raiseHook)(Error_Block*);
VALUES
eb — non-NULL pointer to an Error_Block
Even if the client passes a NULL error block pointer, this parameter is always non-NULL.
DETAILS
This 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.
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 or NULL
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
String 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 or NULL
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_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 or NULL
If eb is NULL 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 or NULL
If eb is NULL 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
 
XDCscript usage meta-domain 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.NUMARGS

Maximum number of arguments supported by an error

XDCscript usage meta-domain
const Error.NUMARGS = 2;
C SYNOPSIS
enum Error.Policy

Error handling policies

XDCscript usage meta-domain
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.
UNWIND — Errors are returned to the caller. A call to Error_raise will return back to the caller.
DETAILS
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.
C SYNOPSIS
struct Error.Data

Error args

XDCscript usage meta-domain
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

XDCscript usage meta-domain
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

XDCscript usage meta-domain
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

XDCscript usage meta-domain
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

XDCscript usage meta-domain
Error.E_msgCode = Error.Desc {
    msg: "%s 0x%x"
};
C SYNOPSIS
config Error.maxDepth  // module-wide

Maximum number of concurrent calls to raiseHook

XDCscript usage meta-domain
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

XDCscript usage meta-domain
Error.policy = Error.Policy Error.UNWIND;
C SYNOPSIS
config Error.raiseHook  // module-wide

The function to call whenever an error is raised

XDCscript usage meta-domain
Error.raiseHook = Void(*)(Error.Block*) Error.print;
VALUES
eb — non-NULL pointer to an Error_Block
Even if the client passes a NULL error block pointer, this parameter is always non-NULL.
DETAILS
This 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.
SEE
C SYNOPSIS
metaonly config Error.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
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, 03 Feb 2011 19:01:53 GMT