##
## Copyright (c) 2001-2002 The OSSP Project .
##
## ex.pod: exception library manual page
##
=pod
=head1 NAME
B - Exception Library
=head1 SYNOPSIS
B I;
B { ... } B (I) { ... }
B(I, I, I);
B;
=head1 DESCRIPTION
B is a small ISO-C++ style exception handling library for use
in the ISO-C language. It allows you to use the paradigm of throwing
and catching exceptions in order to reduce the amount of error handling
code in without making your program less robust. This is achieved
by directly transferring exceptional return codes (and the program
control flow) from the location where it was raised (throw point) to
the location where it is handled (catch point) - usually from a deeply
nested sub-routine to a parent routine. All intermediate routines
no longer have to make sure that the exceptional return codes from
sub-routines are correctly passed back to the parent.
=head2 EXCEPTIONS
An exception is a triple EI,I,IE where
I identifies the class of the exception thrower, I
identifies the particular class instance of the exception thrower, and
I is the exceptional return code the thrower wants to send to the
catcher. All three parts are of type C internally, but every
value can be used which can be (automatically) casted to a C.
Exceptions are created on-the-fly by the B command.
=head2 APPLICATION PROGRAMMER INTERFACE (API)
The B API consists of four different elements:
=over 4
=item B I;
This is the declaration of an exception variable. It is usually never
initialized manually. Instead it is initialized by an B block
and just used read-only inside the block. Such a variable of type
B consists of six attributes:
=over 2
=item CI
This is the I argument of the B call which created
the exception. This globally and uniquely identifies the class of
I. Usually this is a pointer to a static object (variable,
structure or function) which identifies the thrower.
=item CI
This is the I argument of the B call which created
the exception. This globally and uniquely identifies the class instance
of I (in case multiple instances exists). Usually this a
pointer to a dynamic object (structure) which identifiers the particular
instance of the thrower.
=item CI
This is the I argument of the B call which created the
exception. This is the exceptional return code which uniquely identifies
the type of exception. Usually this is the value which is Ced
if no exceptions would be thrown. In the simple case this is just a
numerical return code. In the complex case this can be a pointer to an
arbitrary complex data structure describing the exception.
=item CI
This is the file name of the source where the B call
was performed. It is provided as an additional information about
the throw point and is intended mainly for tracing and debugging
purposes.
=item C I
This is the line number inside the source file name where the
B call was performed. It is provided as an additional
information about the throw point and is intended mainly for tracing and
debugging purposes.
=item CI
This is the function name (if determinable, else "C<#NA#>") inside
the source file name where the B call was performed. It is
provided as an additional information about the throw point and is
intended mainly for tracing and debugging purposes.
=back
=item B { ... } B (I) { ... }
This is the main construct provided by B. It is modeled after
the ISO-C++ C-C construct which in turn is very similar to
an ISO-C C-C construct. It consists of an B block
which forms the dynamic scope of the exception handling (i.e. exceptions
thrown there are or from routines called from there are catched) and a
B block where the caught exceptions are handled.
The B and B cannot be used seperately, they work only
in combination. In contrast to ISO-C++ there is only one B
block and not multiple ones (all B exceptions are of the
same ISO-C type B). If an exception is caught, it is stored in
I for inspection (or re-throwing) inside the B
block. Although declared outside, the I is only valid
within the B block. But it can be re-used in following
B/B constructs, of course.
The B block is a regular ISO-C language block, but it is not
allowed to jump into it via C or C(3) or out of it via
C, C or C(3) because there is some hidden setup
and cleanup that needs to be done by B regardless of whether an
exception is caught. Jumping into an B clause would avoid doing
the setup, and jumping out of it would avoid doing the cleanup. In both
cases the result is a broken exception facility.
The B block is a regular ISO-C language block without any
restrictions.
=item B(I, I, I);
This is second main construct. It builds an exception from the supplied
arguments and throws it. If an B/B clause exists in
the dynamic scope of the B call, this exception is copied into
the I of B and the program control flow is continued
in the B block. If no B/B clause exists in
the dynamic scope of the B call, the program C(3)s. The
B can be performed everywhere, including inside B and
B blocks.
=item B;
This is only valid within an B block and re-throws
the current exception (in I). It is similar to the
call B(I.ex_class, I.ex_object,
I.ex_value) but with the difference that the C,
C and C elements of the thrown exception are kept.
=back
=head1 EXAMPLE
#include "ex.h"
ex_t e;
ex_try {
...
ex_throw (..., ..., 123);
...
}
ex_catch (e) {
...
if ((int)e->ex_value == 123)
...
else if ((int)e->ex_value == 456)
...
else
ex_rethrow;
...
}
=head1 SEE ALSO
C++ try/catch/throw language directives;
setjmp(3), longjmp(3), sigsetjmp(3), siglongjmp(3).
=head1 HISTORY
B was invented in January 2002 by Ralf S. Engelschall for use
inside the OSSP project. Its creation was prompted by the requirement to
reduce the error handling inside B. The implementation
is partly derived from B 2.0.0, a similar library written 2000
by Adam M. Costello Eamc@cs.berkeley.eduE and Cosmin Truta
Ecosmin@cs.toronto.eduE.
=head1 AUTHORS
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
=cut