TaPAS  0.2
Macros | Typedefs | Functions | Variables
ccl-exception.h File Reference

An exception mechanism. More...

#include <ccl/ccl-common.h>
#include <ccl/ccl-protos.h>
#include <setjmp.h>

Go to the source code of this file.

Macros

#define CCL_THROW(_args_)
 Dummy macro-function allowing to indicate exceptions thrown by a function. More...
 
#define CCL_DECLARE_EXCEPTION(exc, super)   extern const ccl_exception_type CCL_EXCEPTION_NAME (exc)
 Macro-function used to declare an exception exc. More...
 
#define CCL_DEFINE_EXCEPTION(exc, super)
 Macro-function used to define an new exception kind exc inheriting from super kind.
 
#define CCL_EXCEPTION_NAME(exc)   ccl_exception_ ## exc
 Macro-function that build the symbol for exceptions used by macro-functions for the definition and declaration of new exceptions (see CCL_DEFINE_EXCEPTION and CCL_DECLARE_EXCEPTION).
 
#define ccl_try(_extype_)
 Stacks a new context permitting to catch exception of kind extype More...
 
#define ccl_catch
 Begins the treatment part of exception. This statement is used after the code put into a ccl_try context. It is followed by a code that handle raised exception.
 
#define ccl_end_try
 Statement that MUST be used after the ccl_catch statement to correctly close a ccl_try statement.
 
#define ccl_trycatch(_extype_, _stmt_)   ccl_try (_extype_) _stmt_ ccl_catch ccl_end_try
 Simple statement that simply catches (without other treatment) extype exceptions thrown by the statement stmt.
 
#define ccl_no_catch
 Statement used to ignore raised exceptions (up to the kind specified in the ccl_try statement). After this statement ccl_end_try should not be used.
 
#define ccl_throw(_extype, _msg)   ccl_throw__ (&CCL_EXCEPTION_NAME (_extype), _msg, __FILE__, __LINE__)
 Throws an exception of type _extype. The message _msg is associated with the exception and could be retrieve via the ccl_exception_current_message variable. More...
 
#define ccl_throw_no_msg(_extype)   ccl_throw (_extype, # _extype)
 Behaves like ccl_throw but the message is replaced by the name of the exception.
 
#define ccl_rethrow()   ccl_rethrow__ (__FILE__, __LINE__)
 Throws an exception with same type than the last exception raised. This function is useful in ccl_catch statements after a local treatment of an exception.
 
#define ccl_exception_is_raised(_e_)   ccl_exception_is_raised__ (&CCL_EXCEPTION_NAME (_e_))
 Checks if the last raised exception is a e or inherits from this type.
 

Typedefs

typedef struct ccl_exception_st ccl_exception
 Type of exception objects.
 
typedef struct
ccl_exception_type_st 
ccl_exception_type
 Type encoding the kind of an exception.
 

Functions

 CCL_DECLARE_EXCEPTION (error, ___toplevel_throwable)
 Top-level exception kind for errors.
 
 CCL_DECLARE_EXCEPTION (exception, ___toplevel_throwable)
 Top-level exception kind for exceptions.
 
 CCL_DECLARE_EXCEPTION (internal_error, error)
 Special ccl_exception_error kind raised when an abnormal behavior is detected by the program.
 
 CCL_DECLARE_EXCEPTION (runtime_exception, exception)
 Special ccl_exception_exception raised during normal operation of the program.
 
 CCL_DECLARE_EXCEPTION (division_by_zero, runtime_exception)
 Special ccl_exception_exception raised when a division by zero occurs.
 
void ccl_exception_print (void)
 Print a message on CCL_LOG_ERROR that locates the last exception and its associated error message.
 

Variables

const char * ccl_exception_current_message
 Message of the last raised exception. If no exception has been raised the content of this variable is undefined.
 

Detailed Description

An exception mechanism.

This module implements exceptions for ANSI C programs. The implementation is based on the setjmp and longjmp standard functions. This code is inspired by the one of A. Braquelaire (http://www.labri.fr/~achille/).

Definition and declarations of exceptions

A new exception kind, say ex, is created using the following statement generally at the top-level scope:

CCL_DEFINE_EXCEPTION(ex, parent);

ex is the name for the exception kind and parent is the name of a parent kind.

Exception are organized hierarchically. An exception of kind ex can be caught by any code that declares to catch ex exceptions or one of its ancestors in the hierarchy of exceptions.

The macro creates a new symbol based on ex (generated by the macro CCL_EXCEPTION_NAME) that should not be used directly.

The module pre-defines some kind of exceptions:

Exceptions can be declared e.g. in header files using the following statement:

* CCL_DECLARE_EXCEPTION(ex, parent);
*

Raise of exceptions.

An exception can be raised (or thrown) for several reasons: detected errors, unexpected behaviors, algorithmic issues, ... Assume that there exists some kind of exception, say my_exception, then the following code

* if (some_condition_is_true)
* ccl_throw(my_exception, "hum! something wrong occurs !");
*

raised an exception of kind my_exception. The throw of the exception is accompagned with a explanation message that can be used by caller codes. If no message has to be sent ccl_throw_no_msg can be used in place of ccl_throw.

One can use the dummy macro-function CCL_THROW to indicate after the declaration of a function that this latter raised exceptions. Example:

* extern int read_and_parse_line_of_file (const char *filename)
* CCL_THROW (io_exception parser_exception);
*

The CCL_THROW generates no code.

Handling exceptions

The ccl_try(ex) statement is used to indicate that one wants to handle exceptions of kined ex raised by the next block of code. The block of code handled by the ccl_try statement is immediatly followed by:

Example:

* extern int read_and_parse_line_of_file (const char *filename)
* CCL_THROW (io_exception parser_exception);
*
* int my_function(void)
* {
* ccl_try (parser_exception)
* {
* read_and_parse_line_of_file ("file_to_read");
* }
* {
* ... code that treats the exception ...
* }
* }
*

On this example, one can remark that the ccl_try only handle exceptions of kind parser_exception. That means that, if an io_exception occurs, it is not handled by this code. If no treatment is done then the lines from ccl_catch ... ccl_end_try can be replaced by ccl_no_catch;

In a ccl_catch ... ccl_end_try block one can use ccl_rethrow to re-throw the last raised exception (this is useful to propagate error treatements).

ccl_try can have been positioned for a general kind of exception (e.g. the pre-defined exception kind). In this case it can be useful to check what kind of exception has been raised. This test is realized by ccl_exception_is_raised.

Definition in file ccl-exception.h.

Macro Definition Documentation

#define CCL_DECLARE_EXCEPTION (   exc,
  super 
)    extern const ccl_exception_type CCL_EXCEPTION_NAME (exc)

Macro-function used to declare an exception exc.

Parameters
excthe name of the exception kind
superindicates that exc is a kind of (or inherits from) super. (for information purpose only, not actually used by the macro).

Definition at line 167 of file ccl-exception.h.

#define CCL_THROW (   _args_)

Dummy macro-function allowing to indicate exceptions thrown by a function.

Parameters
<em>args</em>space separated list of thrown exceptions

Definition at line 159 of file ccl-exception.h.

#define ccl_throw (   _extype,
  _msg 
)    ccl_throw__ (&CCL_EXCEPTION_NAME (_extype), _msg, __FILE__, __LINE__)

Throws an exception of type _extype. The message _msg is associated with the exception and could be retrieve via the ccl_exception_current_message variable.

If the exception is not caught by a ccl_try statement handling _extype kind of exceptions, a message indicates the location of this throw and the program is aborted.

Definition at line 285 of file ccl-exception.h.

#define ccl_try (   _extype_)
Value:
do { \
ccl_exception_push (&here, &CCL_EXCEPTION_NAME (_extype_)); \
if (setjmp (here.context) == 0) \
{
struct ccl_exception_st ccl_exception
Type of exception objects.
#define CCL_EXCEPTION_NAME(exc)
Macro-function that build the symbol for exceptions used by macro-functions for the definition and de...

Stacks a new context permitting to catch exception of kind extype

Exception with (or inheriting of) the kind extype can be caught and treated using the ccl_catch statement or ignored with ccl_no_catch.

Definition at line 229 of file ccl-exception.h.