Error.h File Reference

Detailed Description

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 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.

The Error.policy configuration parameter defines what happens when an error is raised. If Error.policy is set to "Error_UNWIND", the error will be captured in the error block and control will be returned to the caller. If Error.policy is set to "Error_TERMINATE", System_abort() will be called when an error is raised.

The Error.raiseHook configuration parameter allows a configured function to be invoked when an 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 Error_getMsg() to extract information from an error block.

Example 1: 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 "Error_UNWIND".

#include <ti/sysbios/runtime/Error.h>
#include <ti/sysbios/knl/Task.h>

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

---

Example 2: The following C code shows that you may pass a special constant Error_ABORT (NULL) 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 System_abort()), thus execution control will never return to the caller.

#include <ti/sysbios/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 3: 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 <ti/sysbios/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...
}

---

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for Error.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Error_Block
	Error block. More...

Macros
#define	Error_E_memory   "out of memory: heap=0x%x, size=%u"
	Out of memory error. More...
#define	Error_E_generic   "error %s"
	Generic error. More...
#define	Error_IGNORE   (&Error_ignore)
	A pointer to a special Error_Block used when the caller does not want to check Error_Block. More...
#define	Error_ABORT   NULL
	A special Error_Block pointer that terminates the application in case of an error. More...

Typedefs
typedef struct Error_Block	Error_Block
	Error block. More...
typedef void(*	Error_HookFxn) (Error_Block *eb)

Functions
bool	Error_check (Error_Block *eb)
	Return true if an error was raised. More...
void	Error_init (Error_Block *eb)
	Initialize an error block. More...
void	Error_print (Error_Block *eb)
	Print error using System.printf() More...

Macro Definition Documentation

Error_E_memory

#define Error_E_memory   "out of memory: heap=0x%x, size=%u"

Out of memory error.

The first parameter must be the heap instance handle. The second parameter is the size of the object for which the allocation failed.

Error_E_generic

#define Error_E_generic   "error %s"

Generic error.

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 also

System::extendedFormats

System::printf

Error_IGNORE

#define Error_IGNORE   (&Error_ignore)

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

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. The configuration parameter, 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".

Error_ABORT

#define Error_ABORT   NULL

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

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 the Error.policy configuration parameter setting.

Typedef Documentation

Error_Block

typedef struct Error_Block Error_Block

Error block.

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.

Error_HookFxn

typedef void(* Error_HookFxn) (Error_Block *eb)

Function Documentation

Error_check()

bool Error_check

(

Error_Block *

eb

)

Return true if an error was raised.

If eb is non-NULL and Error.policy is set to Error_UNWIND and an error was raised on eb, this function returns true. Otherwise, it returns false.

Parameters

eb	pointer to an Error_Block, Error_ABORT or Error_IGNORE

Return values

true	if an error was raised, false if no error raised

Error_init()

void Error_init

(

Error_Block *

eb

)

Initialize an error block.

If eb is non-NULL, initialize the fields in the error block to 0.

Parameters

eb	pointer to an Error_Block

Error_print()

void Error_print

(

Error_Block *

eb

)

Print error using System.printf()

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:

Error_raised: {err_msg} ({file}:{line})

where "{file}" and "{line} are the file and line at the Error_raise() call site, and "{err_msg}" is the error message rendered with the arguments associated with the error.

If "eb" is "Error_ABORT" or "Error_IGNORE", this function simply returns with no output.

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.

Parameters

eb	pointer to an "Error_Block", "Error_ABORT" or "Error_IGNORE"