module xdc.runtime.Error

Runtime error manager

C synopsis
Individual elements
DETAILS
EXAMPLES
XDCscript usage
Individual elements

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	Error_check// Return TRUE if an error was raised(Error_Block *eb);
UInt16	Error_getCode// Get an error's code(Error_Block *eb);
Error_Data *	Error_getData// Get an error's argument list(Error_Block *eb);
Error_Id	Error_getId// Get an error's id(Error_Block *eb);
String	Error_getMsg// Get an error's "printf" format string(Error_Block *eb);
Types_Site *	Error_getSite// Get an error's call site info(Error_Block *eb);
Void	Error_init// Put an error block into its initial state(Error_Block *eb);
Void	Error_print// Print error using System.printf()(Error_Block *eb);
macro Void	Error_raise// Raise an error(Error_Block *eb, Error_Id id, IArg arg1, IArg arg2);
Functions common to all target modules
	Error_Module_getMask// Returns the diagnostics mask for this module, Error_Module_hasMask// Test whether this module has a diagnostics mask, Error_Module_heap// The heap from which this module allocates memory, Error_Module_id// Get this module's unique id, Error_Module_setMask// Set the diagnostics mask for this module, Error_Module_startupDone// Test if this module has completed startup
Defines
#define	Error_NUMARGS// Maximum number of arguments supported by an error (Int)2
Typedefs
typedef struct	Error_Block// Error block Error_Block;
typedef struct	Error_Data// Error args ...
typedef Void	(Error_HookFxn// Function called whenever an error is raised)(Error_Block);
typedef opaque	Error_Id// Error identifier;
typedef enum	Error_Policy// Error handling policies ...
Constants
extern const Error_Id	Error_E_generic// Generic error;
extern const Error_Id	Error_E_memory// Out of memory error;
extern const Error_Id	Error_E_msgCode// Generic error that displays a string and a numeric value;
extern const UInt16	Error_maxDepth// Maximum number of concurrent calls to `raiseHook`;
extern const Error_Policy	Error_policy// System-wide error handling policy;
extern const Error_HookFxn	Error_raiseHook// The function to call whenever an error is raised;

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