ossp-pkg/ex/ex.pod
1.2
##
## Copyright (c) 2001-2002 The OSSP Project <http://www.ossp.org/>
## Copyright (c) 2001-2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
##
## This file is part of OSSP ex, an exception library
## which can be found at http://www.ossp.org/pkg/ex/.
##
## This program is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License
## as published by the Free Software Foundation; either version
## 2.0 of the License, or (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this file; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
## USA, or contact the OSSP project <ossp@ossp.org>.
##
## ex.pod: exception library manual page
##
=pod
=head1 NAME
B<OSSP ex> - Exception Library
=head1 SYNOPSIS
B<ex_t> I<variable>;
B<ex_try> { ... } B<ex_catch> (I<variable>) { ... }
B<ex_throw>(I<class>, I<object>, I<value>);
B<ex_rethrow>;
=head1 DESCRIPTION
B<OSSP ex> 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 E<lt>I<class>,I<object>,I<value>E<gt> where
I<class> identifies the class of the exception thrower, I<object>
identifies the particular class instance of the exception thrower, and
I<value> is the exceptional return code the thrower wants to send to the
catcher. All three parts are of type C<void *> internally, but every
value can be used which can be (automatically) casted to a C<void *>.
Exceptions are created on-the-fly by the B<ex_throw> command.
=head2 APPLICATION PROGRAMMER INTERFACE (API)
The B<OSSP ex> API consists of four different elements:
=over 4
=item B<ex_t> I<variable>;
This is the declaration of an exception variable. It is usually never
initialized manually. Instead it is initialized by an B<ex_catch> block
and just used read-only inside the block. Such a variable of type
B<ex_t> consists of six attributes:
=over 2
=item C<void *>I<ex_class>
This is the I<class> argument of the B<ex_throw> call which created
the exception. This globally and uniquely identifies the class of
I<ex_value>. Usually this is a pointer to a static object (variable,
structure or function) which identifies the thrower.
=item C<void *>I<ex_object>
This is the I<object> argument of the B<ex_throw> call which created
the exception. This globally and uniquely identifies the class instance
of I<ex_value> (in case multiple instances exists). Usually this a
pointer to a dynamic object (structure) which identifiers the particular
instance of the thrower.
=item C<void *>I<ex_value>
This is the I<value> argument of the B<ex_throw> 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 C<return>ed
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 C<char *>I<ex_file>
This is the file name of the source where the B<ex_throw> 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<int> I<ex_line>
This is the line number inside the source file name where the
B<ex_throw> 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<char *>I<ex_func>
This is the function name (if determinable, else "C<#NA#>") inside
the source file name where the B<ex_throw> 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<ex_try> { ... } B<ex_catch> (I<variable>) { ... }
This is the main construct provided by B<OSSP ex>. It is modeled after
the ISO-C++ C<try>-C<catch> construct which in turn is very similar to
an ISO-C C<if>-C<else> construct. It consists of an B<ex_try> 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<ex_catch> block where the caught exceptions are handled.
The B<ex_trx> and B<ex_catch> cannot be used seperately, they work only
in combination. In contrast to ISO-C++ there is only one B<ex_catch>
block and not multiple ones (all B<OSSP ex> exceptions are of the
same ISO-C type B<ex_t>). If an exception is caught, it is stored in
I<variable> for inspection (or re-throwing) inside the B<ex_catch>
block. Although declared outside, the I<variable> is only valid
within the B<ex_catch> block. But it can be re-used in following
B<ex_try>/B<ex_catch> constructs, of course.
The B<ex_try> block is a regular ISO-C language block, but it is not
allowed to jump into it via C<goto> or C<longjmp>(3) or out of it via
C<return>, C<goto> or C<longjmp>(3) because there is some hidden setup
and cleanup that needs to be done by B<OSSP ex> regardless of whether an
exception is caught. Jumping into an B<ex_try> 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. Nevertheless you are
allowed to nest B<ex_try> clauses.
The B<ex_catch> block is a regular ISO-C language block without any
restrictions.
=item B<ex_throw>(I<class>, I<object>, I<value>);
This is second main construct. It builds an exception from the supplied
arguments and throws it. If an B<ex_try>/B<ex_catch> clause exists in
the dynamic scope of the B<ex_throw> call, this exception is copied into
the I<variable> of B<ex_catch> and the program control flow is continued
in the B<ex_catch> block. If no B<ex_try>/B<ex_catch> clause exists in
the dynamic scope of the B<ex_throw> call, the program C<abort>(3)s. The
B<ex_throw> can be performed everywhere, including inside B<ex_try> and
B<ex_catch> blocks.
=item B<ex_rethrow>;
This is only valid within an B<ex_catch> block and re-throws
the current exception (in I<variable>). It is similar to the
call B<ex_throw>(I<variable>.ex_class, I<variable>.ex_object,
I<variable>.ex_value) but with the difference that the C<ex_file>,
C<ex_line> and C<ex_func> 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<OSSP ex> 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<OSSP lmtp2nntp>. The implementation
is partly derived from B<cexcept> 2.0.0, a similar library written 2000
by Adam M. Costello E<lt>amc@cs.berkeley.eduE<gt> and Cosmin Truta
E<lt>cosmin@cs.toronto.eduE<gt>.
=head1 AUTHORS
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
=cut
