OSSP CVS Repository

ossp - Difference in ossp-pkg/ex/ex.pod versions 1.26 and 1.27
Not logged in
[Honeypot]  [Browse]  [Home]  [Login]  [Reports
[Search]  [Ticket]  [Timeline
  [History

ossp-pkg/ex/ex.pod 1.26 -> 1.27

--- ex.pod       2003/01/06 15:31:24     1.26
+++ ex.pod       2003/01/30 10:23:12     1.27
@@ -79,8 +79,8 @@
 class of the exception thrower, I<object> identifies the particular
 class instance of the exception thrower, and I<value> is the exceptional
 return code value the thrower wants to communicate. All three parts are
-of type "C<void *>" internally, but every value is useable which can
-be lossless casted this type. Exceptions are created on-the-fly by the
+of type "C<void *>" internally, but every value is useable which can be
+lossless "casted" to this type. Exceptions are created on-the-fly by the
 B<ex_throw> command.
 
 =head2 APPLICATION PROGRAMMER INTERFACE (API)
@@ -101,19 +101,20 @@
 =item C<void *>I<ex_class>
 
 This is the I<class> argument of the B<ex_throw> call which created
-the exception. This should globally and uniquely identify the class of
-I<ex_value>. Usually this is a pointer to a static object (variable,
-structure or function) which identifies the class of the thrower and
-allows the catcher to correctly handle I<ex_value>.
+the exception. This can globally and uniquely identify the class to
+which I<ex_value> belongs to . Usually this is a pointer to a static
+object (variable, structure or function) which identifies the class of
+the thrower and allows the catcher to correctly handle I<ex_value>. It
+is usually just an additional (optional) information to I<ex_value>.
 
 =item C<void *>I<ex_object>
 
-This is the I<object> argument of the B<ex_throw> call which created
-the exception. This should globally and uniquely identify the class
-instance of I<ex_value> (in case multiple instances exists at all).
+This is the I<object> argument of the B<ex_throw> call which created the
+exception. This can globally and uniquely identify the class instance
+I<ex_value> belongs to (in case multiple instances exists at all).
 Usually this a pointer to a dynamic object (structure) which identifiers
 the particular instance of the thrower. It is usually just an additional
-information to I<ex_value>.
+(optional) information to I<ex_value>.
 
 =item C<void *>I<ex_value>
 
@@ -127,22 +128,23 @@
 =item C<char *>I<ex_file>
 
 This is the file name of the B<ISO-C> 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.
+was performed. It is automatically 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 B<ISO-C> 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.
+This is the line number inside the B<ISO-C> source file name where the
+B<ex_throw> call was performed. It is automatically 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
 B<ISO-C> 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.
+is automatically provided as an additional information about the throw
+point and is intended mainly for tracing and debugging purposes.
 
 =back
 
@@ -174,8 +176,8 @@
 B<ex_catch> clauses, of course.
 
 The B<ex_try> 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 there
+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 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
@@ -191,7 +193,7 @@
 B<ex_try> blocks: all accessible B<ISO-C> objects have the (expected)
 values as of the time B<ex_throw> was called, except that the values
 of objects of automatic storage invocation duration that do not have
-the C<volatile> storage class I<and> have been changed between the
+the "C<volatile>" storage class I<and> have been changed between the
 B<ex_try> invocation and B<ex_throw> are indeterminate. This is because
 both you usually do not know which commands in the B<ex_try> were
 already successful before the exception was thrown (logically speaking)
@@ -202,11 +204,12 @@
 
 This builds an exception from the supplied arguments and throws it.
 If an B<ex_try>/B<ex_catch> clause formed the dynamic scope of the
-B<ex_throw> call, this exception is copied into the I<variable> of its
-B<ex_catch> clause 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_throw> call, this exception is copied into the I<variable> of
+its B<ex_catch> clause and the program control flow is continued in
+the (optional B<ex_cleanup> and then 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 calls C<abort>(3). The B<ex_throw> can
+be performed everywhere, including inside B<ex_try>, B<ex_cleanup> and
 B<ex_catch> blocks.
 
 =item B<ex_rethrow>;
@@ -222,50 +225,51 @@
 
 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.
+B<ex_throw> operations are remembered but deferred and on leaving the
+I<BLOCK> the I<first> occurred exception is thrown. The second and
+subsequent exceptions are ignored.
+
+The B<ex_defer> block I<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
 of exceptions, i.e., inside the dynamic scope of B<ex_shield> all
-B<ex_throw> operations are silently ignored.
+B<ex_throw> operations are just silently ignored.
 
 The B<ex_shield> 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 shielding level to become out of sync. Jumping into
-an B<ex_shield> clause would avoid increasing the exception shielding
-level, and jumping out of it would avoid decreasing it. In both cases
-the result is an incorrect exception shielding level. Nevertheless you
-are allowed to nest B<ex_shield> clauses.
+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 shielding level to become out of sync.
+Jumping into an B<ex_shield> clause would avoid increasing the exception
+shielding level, and jumping out of it would avoid decreasing it.
+In both cases the result is an incorrect exception shielding level.
+Nevertheless you are allowed to nest B<ex_shield> clauses.
 
 =item B<ex_catching>
 
 This is a boolean flag which can be checked inside the dynamic scope
 of an B<ex_try> clause to test whether the current scope is exception
-catching.
+catching (see B<ex_try>/B<ex_catch> clause).
 
 =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.
+deferring (see B<ex_defer> clause).
 
 =item B<ex_shielding>
 
 This is a boolean flag which can be checked inside the dynamic scope of
 an B<ex_shield> clause to test whether the current scope is exception
-shielding.
+shielding (see B<ex_shield> clause).
 
 =back
 
@@ -311,7 +315,7 @@
 
 =back
 
-The default implementation (define C<__EX_MCTX_SJLJ__> or as long
+The default implementation (define C<__EX_MCTX_SJLJ__> or as long as
 C<__EX_MCTX_CUSTOM__> is not defined) uses the B<ISO-C> jmp_buf(3)
 facility:
 
@@ -334,8 +338,9 @@
 
 By default, B<__ex_ctx> (which is B<__ex_ctx_default> as provided by
 F<libex>) returns a pointer to a static C<ex_ctx_t> context. For use in
-multi-threading environments, this should be overwritten with a callback
-function returning a per-thread context structure.
+multi-threading environments, this should be overwritten with a
+callback function returning a per-thread context structure (see section
+B<MULTITHREADING ENVIRONMENTS> below).
 
 To initialize an exception context structure there are two macros
 defined: "B<EX_CTX_INITIALIZER>" for static initialization and
@@ -347,15 +352,17 @@
 In case there is an exception thrown which is not caught by any
 B<ex_try>/B<ex_catch> clauses, B<OSSP ex> calls the callback "C<void
 (*>B<__ex_terminate>C<)(ex_t *)>". It receives a pointer to the
-exception object which should have been thrown.
+exception object which was thrown.
 
 By default, B<__ex_terminate> (which is B<__ex_terminate_default>
 as provided by F<libex>) prints a message of the form "C<**EX:
 UNCAUGHT EXCEPTION: class=0xXXXXXXXX object=0xXXXXXXXX value=0xXXXXXXX
 [xxxx:NNN:xxxx]>" to F<stderr> and then calls abort(3) in order to
 terminate the application. For use in multi-threading environments, this
-should be overwritten with a callback function which terminates only the
-current thread.
+should be overwritten with a callback function which terminates only
+the current thread. Even better, a real application always should have
+a top-level B<ex_try>/B<ex_catch> clause in its "C<main()>" in order to
+more gracefully terminate the application.
 
 =head2 Namespace Mapping
 
@@ -395,7 +402,7 @@
      strcpy(cp1, "foo");
      strcpy(cp2, "bar");
  }
- ex_clean {
+ ex_cleanup {
      if (cp3 != NULL) free(cp3);
      if (cp2 != NULL) free(cp2);
      if (cp1 != NULL) free(cp1);
@@ -411,59 +418,59 @@
 
 =item B<01: variable scope>
 
-Variables which are used in the B<ex_clean> or B<ex_catch> clauses
+Variables which are used in the B<ex_cleanup> or B<ex_catch> clauses
 must be declared before the B<ex_try> clause, otherwise they only
 exist inside the B<ex_try> block. In the example above, C<cp1>, C<cp2>
 and C<cp3> are automatic variables and only exist in the block of the
-B<ex_try> clause, the code in the B<ex_clean> and B<ex_catch> clauses
+B<ex_try> clause, the code in the B<ex_cleanup> and B<ex_catch> clauses
 does not know anything about them.
 
 =item B<02: variable initialization>
 
-Variables which are used in the B<ex_clean> or B<ex_catch> clauses must
+Variables which are used in the B<ex_cleanup> or B<ex_catch> clauses must
 be initialized before the point of the first possible B<ex_throw> is
-reached. In the example above, B<ex_clean> would have trouble using
+reached. In the example above, B<ex_cleanup> would have trouble using
 C<cp3> if mallocex() throws a exception when allocating a C<TOOBIG>
 buffer.
 
 =item B<03: volatile variables>
 
-Variables which are used in the B<ex_clean> or B<ex_catch> clauses
-must be declared with the storage class C<volatile>, otherwise they
+Variables which are used in the B<ex_cleanup> or B<ex_catch> clauses
+must be declared with the storage class "C<volatile>", otherwise they
 might contain outdated information if B<ex_throw> throws an exception.
 If using a "free if unset" approach like the example does in the
-B<ex_clean> clause, the variables must be initialized (see B<02>) I<and>
+B<ex_cleanup> clause, the variables must be initialized (see B<02>) I<and>
 remain valid upon use.
 
 =item B<04: clean before catch>
 
-The B<ex_clean> clause is not only written down before the B<ex_catch>
+The B<ex_cleanup> clause is not only written down before the B<ex_catch>
 clause, it is also evaluated before the B<ex_catch> clause. So,
 resources being cleaned up must no longer be used in the B<ex_catch>
 block. The example above would have trouble referencing the character
-strings in the printf(3) statement because these have been free(3)'d
+strings in the printf(3) statement because these have been freed
 before.
 
 =item B<05: variable uninitialization>
 
 If resources are passed away and out of the scope of the
-B<ex_try>/B<ex_clean>/B<ex_catch> construct and the variables were
+B<ex_try>/B<ex_cleanup>/B<ex_catch> construct and the variables were
 initialized for using a "free if unset" approach then they must be
 uninitialized after being passed away. The example above would free(3)
-C<cp1> in the B<ex_clean> clause if mallocex() throws an exception if
+C<cp1> in the B<ex_cleanup> clause if mallocex() throws an exception if
 allocating a C<TOOBIG> buffer. The C<globalcontext-&gt;first> pointer
 hence becomes invalid.
 
 =back
 
-As following is fixed version of the code (annotated with the pitfall
+The following is fixed version of the code (annotated with the pitfall
 items for reference):
 
  /* GOOD EXAMPLE */
  { /*01*/
-     volatile /*03*/ char *cp1 = NULL /*02*/;
-     volatile /*03*/ char *cp2 = NULL /*02*/;
-     volatile /*03*/ char *cp3 = NULL /*02*/;
+     char * volatile /*03*/ cp1 = NULL /*02*/;
+     char * volatile /*03*/ cp2 = NULL /*02*/;
+     char * volatile /*03*/ cp3 = NULL /*02*/;
      try {
          cp1 = mallocex(SMALLAMOUNT);
          globalcontext->first = cp1;
@@ -473,8 +480,8 @@
          strcpy(cp1, "foo");
          strcpy(cp2, "bar");
      }
-     clean {
-  /*04*/ printf("cp3=%s", cp3 == NULL /*02*/ ? "" : cp3);
+     clean { /*04*/
+         printf("cp3=%s", cp3 == NULL /*02*/ ? "" : cp3);
          if (cp3 != NULL)
              free(cp3);
          if (cp2 != NULL)
@@ -487,13 +494,13 @@
      }
  }
 
-An alternative fixed version could also be:
+Alternatively, this could also be used:
 
- /* ALTERNATE *05* GOOD EXAMPLE */
+ /* ALTERNATIVE GOOD EXAMPLE */
  { /*01*/
-     volatile /*03*/ char *cp1 = NULL /*02*/;
-     volatile /*03*/ char *cp2 = NULL /*02*/;
-     volatile /*03*/ char *cp3 = NULL /*02*/;
+     char * volatile /*03*/ cp1 = NULL /*02*/;
+     char * volatile /*03*/ cp2 = NULL /*02*/;
+     char * volatile /*03*/ cp3 = NULL /*02*/;
      try {
          cp1 = mallocex(SMALLAMOUNT);
          globalcontext->first = cp1;
@@ -503,8 +510,8 @@
          strcpy(cp1, "foo");
          strcpy(cp2, "bar");
      }
-     clean {
-  /*04*/ printf("cp3=%s", cp3 == NULL /*02*/ ? "" : cp3);
+     clean { /*04*/
+         printf("cp3=%s", cp3 == NULL /*02*/ ? "" : cp3);
          if (cp3 != NULL)
              free(cp3);
          if (cp2 != NULL)
@@ -518,7 +525,6 @@
      }
  }
 
-
 =head1 MULTITHREADING ENVIRONMENTS
 
 B<OSSP ex> is designed to work both in single-threading and
@@ -534,12 +540,12 @@
 =head2 GNU pth
 
 Using B<OSSP ex> together with B<GNU pth> is straight-forward, because
-B<GNU pth> 1.5 (and higher) already has support for B<OSSP ex> built-in.
+B<GNU pth> 2.0 (and higher) already has support for B<OSSP ex> built-in.
 All which is needed is that B<GNU pth> is configured with the B<GNU
 Autoconf> option C<--with-ex>. Then each B<GNU pth> user-space thread
-has its own B<OSSP ex> exception context automatically. The default
-of using B<ISO-C> jmp_buf(3) does not conflict with the thread
-dispatching mechanisms used by B<GNU pth>.
+has its own B<OSSP ex> exception context automatically. The default of
+using B<ISO-C> jmp_buf(3) does not conflict with the thread dispatching
+mechanisms used by B<GNU pth>.
 
 =head2 POSIX pthreads
 
@@ -550,7 +556,7 @@
 terminates only the current thread. To get an impression, a small
 utility library for this follows:
 
-=over 4
+=over 2
 
 =item F<pthread_ex.h>
 
@@ -560,7 +566,8 @@
  #include <pthread.h>
 
  int pthread_init_ex   (void);
- int pthread_create_ex (pthread_t *, const pthread_attr_t *, void *(*)(void *), void *);
+ int pthread_create_ex (pthread_t *, const pthread_attr_t *,
+                        void *(*)(void *), void *);
 
  #ifndef PTHREAD_EX_INTERNAL
  #define pthread_init   pthread_init_ex
@@ -592,7 +599,8 @@
  /* callback: context fetching */
  static ex_ctx_t *pthread_ex_ctx(void)
  {
-     return (ex_ctx_t *)pthread_getspecific(pthread_ex_ctx_key);
+     return (ex_ctx_t *)
+         pthread_getspecific(pthread_ex_ctx_key);
  }
 
  /* callback: termination */
@@ -606,8 +614,10 @@
  {
      int rc;
 
-     /* additionally create thread data key and override OSSP ex callbacks */
-     pthread_key_create(&pthread_ex_ctx_key, pthread_ex_ctx_destroy);
+     /* additionally create thread data key
+        and override OSSP ex callbacks */
+     pthread_key_create(&pthread_ex_ctx_key,
+                        pthread_ex_ctx_destroy);
      __ex_ctx       = pthread_ex_ctx;
      __ex_terminate = pthread_ex_terminate;
 
@@ -637,14 +647,18 @@
  }
 
  /* pthread_create() wrapper */
- int pthread_create_ex(pthread_t *thread, const pthread_attr_t *attr, void *(*entry)(void *), void *arg)
+ int pthread_create_ex(pthread_t *thread,
+                       const pthread_attr_t *attr,
+                       void *(*entry)(void *), void *arg)
  {
      pthread_create_ex_t wrapper;
 
-     /* spawn thread but execute start function through wrapper */
+     /* spawn thread but execute start
+        function through wrapper */
      wrapper.entry = entry;
      wrapper.arg   = arg;
-     return pthread_create(thread, attr, pthread_create_wrapper, &wrapper);
+     return pthread_create(thread, attr,
+                           pthread_create_wrapper, &wrapper);
  }
 
 =back
@@ -748,7 +762,7 @@
 
 You can achieve this very easily by changing the library as following:
 
-=over 4
+=over 2
 
 =item F<foo.h>
 
@@ -832,7 +846,7 @@
 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
+The B<shield> feature was inspired by an "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.

CVSTrac 2.0.1