4.10.41 xep
Keywords: onyx

Next: 4.11 Dictionaries Up: 4.10 Classes Previous: 4.10.40 tsd Contents Index
Subsections

- 4.10.41.1 API

##
4.10.41 xep

The xep class implements exception handling, with support for xep_try and xep_catch() blocks. Minimal use must include at least:

    xep_begin();
    xep_try
    {
        /* Code that might throw an exception. */
    }
    xep_end();

A more complete skeleton looks like:

    xep_begin();
    xep_try
    {
        /* Code that might throw an exception. */
    }
    xep_catch(SOME_EXCEPTION)
    {
        /* Handle exception... */
        xep_handled();
    }
    xep_catch(ANOTHER_EXCEPTION)
    xep_mcatch(YET_ANOTHER)
    {
        /* React to exception, but propagate... */
    }
    xep_acatch
    {
        /* Handle all exceptions not explicitly handled above... */
        xep_handled();
    }
    xep_end();

Note that there is some serious cpp macro magic behind the xep interface, and as such, if usage deviates significantly from the above templates, compiler errors may result.

Exception values are of type cw_xepv_t . CW_ONYXX_MIN to CW_ONYXX_MAX are reserved by libonyx, and other ranges may be reserved by other libraries. See their documentation for details.

An exception is not implicitly handled if an exception handler is executed for that exception. Instead, xep_handled() must be manually called to avoid propagating the exception up the handler chain.

It is not legal to return from a function within an exception handling code block, nor is it legal to jump out of an exception handling block; doing so will corrupt the exception handler chain.

### 4.10.41.1 API

void xep_begin(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Begin an exception handling code block.

void xep_end(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    End an exception handling block.

xep_try ...:

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Begin a block of code that is to be executed, with the possibility that an exception might be thrown.

xep_catch(cw_xepv_t a_xepv) ...:

  Input(s):
    a_xepv:
      Exception number.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Begin a block of code that catches an exception. The exception is not considered handled unless xep_handled() is called.

xep_mcatch(cw_xepv_t a_xepv) ...:

  Input(s):
    a_xepv:
      Exception number.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Begin a block of code that catches an exception. Must immediately follow a xep_catch() call. This interface is used for the case where more than one exception type is to be handled by the same code block. The exception is not considered handled unless xep_handled() is called.

xep_acatch ...:

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Begin a block of code that catches all exceptions not explicitly caught by xep_catch() and xep_mcatch() blocks. There may only be one xep_acatch block within a try/catch block. The exception is not considered handled unless xep_handled() is called.

cw_xepv_t xep_value(void):

  Input(s):
    None.
  Output(s):
    retval:
      Value of the current exception being handled.
  Exception(s):
    None.
  Description:
    Return the value of the current exception being handled.

const char * xep_filename(void):

  Input(s):
    None.
  Output(s):
    retval:
      Filename where the current exception being handled was thrown.
  Exception(s):
    None.
  Description:
    Return the filename where the current exception being handled was thrown.

uint32_t xep_line_num(void):

  Input(s):
    None.
  Output(s):
    retval:
      Line number where the current exception being handled was thrown.
  Exception(s):
    None.
  Description:
    Return the line number where the current exception being handled was thrown.

void xep_throw_e(cw_xepv_t a_xepv, const char *a_filename, uint32_t a_line_num):

void xep_throw(cw_xepv_t a_xepv):

  Input(s):
    a_xepv:
      Exception number to throw.
    a_filename:
      Should be __FILE__.
    a_line_num:
      Should be __LINE__.
  Output(s):
    None.
  Exception(s):
    a_xepv.
  Description:
    Throw an exception.

void xep_retry(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Implicitly handle the current exception and retry the xep_try code block.

void xep_handled(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Mark the current exception as handled.

Next: 4.11 Dictionaries Up: 4.10 Classes Previous: 4.10.40 tsd Contents Index