From RTSC-Pedia

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC

Using xdc.runtime Errors/Example 1

How to use the Error module

Using the Error module

In the somewhat contrived example below, we show how errors are raised and how they are detected. The function half() raises an error when its argument is not an even number. The main() function initializes an Error_Block, calls half(), and then checks for an error.

Notice that the caller, in this case main(), must first initialize an Error_Block by calling Error_init(). After calling a function that raises errors, the caller uses Error_check() to test whether or not an an error was raised.

#include <xdc/std.h>
 
#include <xdc/runtime/Error.h>
#include <xdc/runtime/System.h>
 
/* ======== half ======== */
static Int half(Int num, Error_Block *eb)
{
    /* raise an error if num is not even */
    if ((num & 0x1) != 0) {
        Error_raise(eb, Error_E_generic, 
            "num must be even", NULL);
    }
    return (num / 2);
}
 
/*  ======== main ======== */
Int main(Int argc, String argv[])
{
    Error_Block eb;
 
    /* must initialize prior to first use */
    Error_init(&eb);
 
    /* call a function that raises an error */
    System_printf("half returned %d\n", half(17, &eb));
 
    /* return 1 if an error occured, 0 otherwise */
    return (Error_check(&eb) ? 1 : 0);
}

var System = xdc.useModule("xdc.runtime.System");
var Error = xdc.useModule("xdc.runtime.Error");

xdc.runtime.Main: "main.c", line 10: generic error: num must be even
half returned 8

For simplicity the half() function uses an existing error ID, Error_E_generic, defined by the Error module itself. We'll see in a later example (Example 4) how to define custom error IDs that allow complete control over the message format string as well as the number and type of the arguments supported by the error.

Error Policies

If we can change the Error policy to terminate on any error rather than "unwind" to the caller, any call to Error_raise() results in a call to System_abort() and control does not return to the caller. In the example above, a call to half() with an odd argument will terminate the program.

In the example below, we only change the Error.policy configuration parameter to Error.TERMINATE and without re-compiling the application it now terminates prior to returning from half(). This can be seen by comparing the output of this application with the previous example; notice that there is no output from the System_printf() function and there is a message from a call to System_abort() made by the Error module.

var Error  = xdc.useModule("xdc.runtime.Error");
var System = xdc.useModule("xdc.runtime.System");
 
Error.policy = Error.TERMINATE;

xdc.runtime.Main: "main.c", line 10: generic error: num must be even
xdc.runtime.Error.raise: terminating execution

Ignoring Errors

In many small-footprint systems, errors are "handled" by aborting the application and restarting; if all errors are fatal, the application never needs to check for error return values and, thereby, eliminate unnecessary code. In cases where any error from a function that raises errors should be treated as a fatal error, it is possible to simply call the function with a NULL Error_Block reference. In effect, the caller is specifying that if an error occurs the application can not proceed and it must abort (via System_abort()).

If we modify our original example to pass NULL rather than an initialized Error_block, you'll see that the application aborts immediately upon passing an odd value to half(). Notice that the output is identical to output we got by setting the Error policy to Error.TERMINATE. Passing a NULL error block reference is effectively the same as setting the Error policy to Error.TERMINATE for the just the function being called.

#include <xdc/std.h>
 
#include <xdc/runtime/Error.h>
#include <xdc/runtime/System.h>
 
/* ======== half ======== */
static Int half(Int num, Error_Block *eb)
{
    /* raise an error if num is not even */
    if ((num & 0x1) != 0) {
        Error_raise(eb, Error_E_generic, 
            "num must be even", NULL);
    }
    return (num / 2);
}
 
/*  ======== main ======== */
Int main(Int argc, String argv[])
{
    /* call half() with NULL Error_Block reference */
    System_printf("half returned %d\n", half(17, NULL));
}

var System = xdc.useModule("xdc.runtime.System");
var Error = xdc.useModule("xdc.runtime.Error");

Running the application above results in the following output.

xdc.runtime.Main: "main.c", line 10: generic error: num must be even
xdc.runtime.Error.raise: terminating execution

See also

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC