An exception mechanism. More...

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

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:

exception
error
internal_error inherits from error
runtime_exception inherits from exception
division_by_zero inherits from runtime_exception

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:

a ccl_catch statement if the exception has to be treated. This block has to be terminated with a ccl_end_try statement.
a ccl_no_catch statement if the exception is ignored.

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");
     }
   ccl_catch
     {
        ... code that treats the exception ...
     }
   ccl_end_try;
}

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

exc	the name of the exception kind
super	indicates 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 here;                                         \
    ccl_exception_push (&here, &CCL_EXCEPTION_NAME (_extype_)); \
    if (setjmp (here.context) == 0)                             \
      {

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.

Macros

Typedefs

Functions

Variables

Detailed Description

Definition and declarations of exceptions

Raise of exceptions.

Handling exceptions

Macro Definition Documentation