Document tools/xbt_exception_checker

git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@2634 48e7efb5-ca39-0410-a469-dd3cf9ba447f

diff --git a/doc/gtut-tour-8-exceptions.doc b/doc/gtut-tour-8-exceptions.doc
index 260b5c3..0d541c0 100644 (file)
--- a/doc/gtut-tour-8-exceptions.doc
+++ b/doc/gtut-tour-8-exceptions.doc
@@ -83,7 +83,13 @@ misusing the exceptions.
 So, as you can see, you don't want to include large sections of your program
 in TRY blocks. If you do so, it's quite sure that one day, you'll do a break
 or a return within this block. And believe me, finding such typos is a real
 So, as you can see, you don't want to include large sections of your program
 in TRY blocks. If you do so, it's quite sure that one day, you'll do a break
 or a return within this block. And believe me, finding such typos is a real

-pain.
+pain. 
+
+If you are suspecting this kind of error, I made a little script for you:
+check <tt>tools/xbt_exception_checker</tt> from the CVS. Given a set of C
+files, it extracts the TRY blocks and display them on the standard output so
+that you can grep for <tt>return</tt>, <tt>break</tt> and such forbidden
+words.

 
 \section GRAS_tut_tour_exceptions_use Putting exceptions into action
 
 
 \section GRAS_tut_tour_exceptions_use Putting exceptions into action
 

diff --git a/include/xbt/ex.h b/include/xbt/ex.h
index 843cf6d..dcdbd7a 100644 (file)
--- a/include/xbt/ex.h
+++ b/include/xbt/ex.h
@@ -157,7 +157,14 @@ typedef struct { __ex_mctx_struct } __ex_mctx_t;
  * This is because there is some hidden setup and
  * cleanup that needs to be done regardless of whether an exception is
  * caught. Bypassing these steps will break the exception handling facility.
  * This is because there is some hidden setup and
  * cleanup that needs to be done regardless of whether an exception is
  * caught. Bypassing these steps will break the exception handling facility.

- *     
+ * The symptom are likely to be a segfault at the next exception raising point,  
+ * ie far away from the point where you did the mistake. If you suspect
+ * that kind of error in your code, have a look at the little script
+ * <tt>tools/xbt_exception_checker</tt> in the CVS. It extracts all the TRY
+ * blocks from a set of C files you give it and display them (and only
+ * them) on the standard output. You can then grep for the forbidden 
+ * keywords on that output.
+ *   

  * The CLEANUP and CATCH blocks are regular ISO-C language statement
  * blocks without any restrictions. You are even allowed to throw (and, in the
  * CATCH block, to re-throw) exceptions.
  * The CLEANUP and CATCH blocks are regular ISO-C language statement
  * blocks without any restrictions. You are even allowed to throw (and, in the
  * CATCH block, to re-throw) exceptions.


@@ -165,7 +172,7 @@ typedef struct { __ex_mctx_struct } __ex_mctx_t;
  * There is one subtle detail you should remember about TRY blocks:
  * Variables used in the CLEANUP or CATCH clauses must be declared with
  * the storage class "volatile", otherwise they might contain outdated
  * There is one subtle detail you should remember about TRY blocks:
  * Variables used in the CLEANUP or CATCH clauses must be declared with
  * the storage class "volatile", otherwise they might contain outdated

- * information if an exception it thrown.
+ * information if an exception is thrown.

  *
  *
  * This is because you usually do not know which commands in the TRY
  *
  *
  * This is because you usually do not know which commands in the TRY