ossp-pkg/ex/ex.pod 1.20 -> 1.21
--- ex.pod 2002/02/25 10:30:15 1.20
+++ ex.pod 2002/03/07 21:30:10 1.21
@@ -48,10 +48,14 @@
B<ex_rethrow>;
+B<ex_defer> I<BLOCK>
+
B<ex_shield> I<BLOCK>
if (B<ex_catching>) ...
+if (B<ex_deferred>) ...
+
if (B<ex_shielding>) ...
=head1 DESCRIPTION
@@ -214,6 +218,22 @@
C<ex_line> and C<ex_func> elements of the caught exception are passed
through as it would have been never caught.
+=item B<ex_defer> I<BLOCK>
+
+This directive executes I<BLOCK> while deferring the throwing of
+exceptions, i.e., inside the dynamic scope of B<ex_defer> all
+B<ex_throw> operations are silently ignored and on leaving the I<BLOCK>
+the first occurred exception is thrown.
+
+The B<ex_defer> block is a regular B<ISO-C> language statement block,
+but it is not allowed to jump into it via C<goto> or C<longjmp>(3) or
+out of it via C<break>, C<return>, C<goto> or C<longjmp>(3) because this
+would cause the deferral level to become out of sync. Jumping into
+an B<ex_defer> clause would avoid increasing the exception deferral
+level, and jumping out of it would avoid decreasing it. In both cases
+the result is an incorrect exception deferral level. Nevertheless you
+are allowed to nest B<ex_defer> clauses.
+
=item B<ex_shield> I<BLOCK>
This directive executes I<BLOCK> while shielding it against the throwing
@@ -235,6 +255,12 @@
of an B<ex_try> clause to test whether the current scope is exception
catching.
+=item B<ex_deferred>
+
+This is a boolean flag which can be checked inside the dynamic scope of
+an B<ex_defer> clause to test whether the current scope is exception
+deferring.
+
=item B<ex_shielding>
This is a boolean flag which can be checked inside the dynamic scope of
@@ -656,7 +682,10 @@
Adam M. Costello E<lt>amc@cs.berkeley.eduE<gt> and Cosmin Truta
E<lt>cosmin@cs.toronto.eduE<gt>. The B<cleanup> clause was inspired by
the B<Java> C<finally> clause. The B<shield> feature was inspired by an
-C<errno> shielding facility used in the B<GNU pth> implementation.
+C<errno> shielding facility used in the B<GNU pth> implementation. The
+B<defer> feature was invented to simplify an application's cleanup
+handling if multiple independent resources are allocated and have to be
+freed on error.
=head1 AUTHORS
|
|
