From RTSC-Pedia

[printable version]

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

Using xdc.runtime Errors/Example 3

Creating a custom error handler

Creating a Custom Error Handler

In this example we show how to create and "install" a custom error handler. Each error raised by an application is optionally passed to a supplied user supplied function. Once an error handler function is created, it is "installed" by setting the Error.raiseHook configuration parameter to point to this function.

In the example below, we start with essentially the same application as Error Example 1 and add an "error hook" function named errHook().

#include <xdc/std.h>
 
#include <xdc/runtime/Error.h>
#include <xdc/runtime/System.h>
#include <xdc/runtime/Types.h>
 
#include <xdc/runtime/Main.h>
#include <xdc/runtime/Assert.h>
 
/* ======== errHook ======== */
Void errHook(Error_Block *eb)
{
    Types_Site *site = Error_getSite(eb);
    Error_Id eid = Error_getId(eb);
 
    /* print user supplied error code */
    System_printf("error %d: ", Error_getCode(eb));
 
    /* check originator's mod id against known mods */
    if (site->mod == Main_Module_id()) {
        System_printf("app error: ");
    }
 
    /* check error id against known errors */
    if (eid == Error_E_generic) {
        System_printf("generic: ");
    }
    else if (eid == Assert_E_assertFailed) {
        System_printf("assertion violation: ");
    }
 
    /* perform default error output */
    Error_print(eb);
}
 
/* ======== half ======== */
static Int half(Int num, Error_Block *eb)
{
    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 a function that raises an error */
    System_printf("half returned %d\n",
        half(17, NULL));
 
    return (0);
}

var Error  = xdc.useModule("xdc.runtime.Error");
var System = xdc.useModule("xdc.runtime.System");
var Main   = xdc.useModule("xdc.runtime.Main");
 
/* set errHook (defined in main.c) as the error 
 * hook function.  Strings begining with '&'
 * can be assigned to function pointers to
 * reference unspecified external functions
 */
Error.raiseHook = "&errHook";
 
/* set user-defined code for E_generic errors */
Error.E_generic.code = 28;

The errHook() function, while not very practical, illustrates the sorts of things that can be tested within an error handler. In particular, it is possible to

• test which module originally raised the error 1,
• test for and specially "handle" specific errors 2, and
• display or log the error 3.

Every RTSC module Mod provides a Mod_Module_id() macro that returns a unique module ID. On line 1 above, we show how this ID can be retrieved and used at runtime to conditionally affect the behavior of the application based on which module raised the error. In this case, Main_Module_id() returns the ID of the xdc.runtime.Main module.

Running the application above results in the following output.

error 28: app error: generic: xdc.runtime.Main: "hook.c", line 66: generic error: num must be even
xdc.runtime.Error.raise: terminating execution

Comparing the output of this example with that of Error Example 1 we see that errHook()

• outputs the error code specified by the user in the configuration script, "error 28:";
• properly detected that the error occurred in the main application and output "app error:";
• determined that the type of error was Error.E_generic and displayed "generic:", and finally
• called the "normal" error print function to output the same information displayed in Example 1.

Error codes can be individually set in configuration script but it's also possible to find and set all error codes in an application or check that every error has a code that has been set.

var Error = xdc.useModule("xdc.runtime.Error");
var mods = xdc.om.$modules;
for (var i = 0; i < mods.length; i++) {
    var M = mods[i];
    for (var f in M) {
        if (M[f] instanceof Error.Id) {
            var err = M[f];
            err.code = 17;
            print("M.$name + "." + f + ".code = " + err.code);
        }
    }
}

See also

[printable version]

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