--- ex.pod 2002/01/30 10:33:36 1.10
+++ ex.pod 2002/01/30 11:11:09 1.11
@@ -36,13 +36,13 @@
B<ex_t> I<variable>;
-B<ex_try> {...} [B<ex_cleanup> {...}] B<ex_catch> (I<variable>) {...}
+B<ex_try> I<BLOCK1> [B<ex_cleanup> I<BLOCK2>] B<ex_catch> (I<variable>) I<BLOCK3>
B<ex_throw>(I<class>, I<object>, I<value>);
B<ex_rethrow>;
-B<ex_shield> {...};
+B<ex_shield> I<BLOCK>
if (B<ex_catching>) ...
@@ -50,30 +50,31 @@
=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 without making your program less robust. This is achieved
+B<OSSP ex> is a small B<ISO-C++> style exception handling library for
+use in the B<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 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.
+control flow) from the location where the exception is 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.
+I<value> is the exceptional return code value 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 the
+B<ISO-C> type "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:
+The B<OSSP ex> API consists of the following elements:
=over 4
@@ -133,38 +134,45 @@
=back
-=item B<ex_try> {...} [B<ex_cleanup> {...}] B<ex_catch> (I<variable>) {...}
+=item B<ex_try> I<BLOCK1> [B<ex_cleanup> I<BLOCK2>] B<ex_catch> (I<variable>) I<BLOCK3>
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
-directly thrown there or thrown from subroutines are catched), an
-optional B<ex_cleanup> block for performing cleanup sequences and a
-B<ex_catch> block where the caught exceptions are handled.
-
-# CONTROL FLOW FIXME!
-
+the B<ISO-C++> C<try>-C<catch> clause which in turn is very similar to
+an B<ISO-C> C<if>-C<else> clause. It consists of an B<ex_try> block
+I<BLOCK1> which forms the dynamic scope of the exception handling (i.e.
+exceptions directly thrown there or thrown from its sub-routines are
+catched), an optional B<ex_cleanup> block I<BLOCK2> for performing
+cleanup operations and an B<ex_catch> block I<BLOCK3> where the caught
+exceptions are handled.
+
+The control flow in case no exception is thrown is simply I<BLOCK1>,
+optionally followed by I<BLOCK2>. I<BLOCK3> is skipped. The control flow
+in case an exception is thrown is: I<BLOCK1> (up to the statement where
+the exception is thrown), optionally followed by I<BLOCK2>, followed by
+I<BLOCK3>.
+
The B<ex_try>, B<ex_cleanup> 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.
+they work only in combination. And in contrast to B<ISO-C++> there
+is only one B<ex_catch> block and not multiple ones (all B<OSSP ex>
+exceptions are of the same B<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 B<ISO-C> language block of
+statement(s), 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_cleanup> and B<ex_catch> blocks are regular B<ISO-C> language
+block of statement(s) without any restrictions. You are even allowed to
+throw (and in the B<ex_catch> block to re-throw) an exception.
=item B<ex_throw>(I<class>, I<object>, I<value>);
@@ -185,11 +193,11 @@
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.
-=item B<ex_shield> {...}
+=item B<ex_shield> I<BLOCK>
-This directive executes its block while shielding against the throwing
-of exceptions, i.e., in the dynamic scope of B<ex_shield> any
-B<ex_throw> operation is ignored.
+This directive executes I<BLOCK> while shielding it against the throwing
+of exceptions, i.e., inside the dynamic scope of B<ex_shield> all
+B<ex_throw> operations are ignored.
=item B<ex_catching>
@@ -246,7 +254,7 @@
=back
The default implementation (define C<__EX_MCTX_USE_SJLJ__> or as long
-C<__EX_MCTX_USE_CUSTOM__> is not defined) uses B<ISO C> jmp_buf(3):
+C<__EX_MCTX_USE_CUSTOM__> is not defined) uses B<ISO-C> jmp_buf(3):
#define __ex_mctx_struct jmp_buf jb;
#define __ex_mctx_save(mctx) (setjmp((mctx)->jb) == 0)
@@ -295,7 +303,7 @@
B<ex_> prefix for the API macros B<ex_try>, B<ex_catch>, B<ex_throw>,
B<ex_rethrow> and B<ex_shield> sometimes have a unpleasant optical
appearance. Especially because B<OSSP rc> is modeled after the exception
-facility in ISO C++ where there is no such prefix on the directives.
+facility in B<ISO-C++> where there is no such prefix on the directives.
For this B<OSSP ex> optionally provides the ability to provide
additional namespace mappings for those API macros. By default (define
|
