summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authornanbor <nanbor@ae88bc3d-4319-0410-8dbf-d08b4c9d3795>1999-01-15 10:05:54 +0000
committernanbor <nanbor@ae88bc3d-4319-0410-8dbf-d08b4c9d3795>1999-01-15 10:05:54 +0000
commit13b9c97b1a5fe842309ffb9987d80e5f67099793 (patch)
tree42a2b7d54710f40cfaa93eac37a1dbf50aa8bb79
parentef08ff914c2cb001d0bcd68ed875c4208d9874a7 (diff)
downloadATCD-13b9c97b1a5fe842309ffb9987d80e5f67099793.tar.gz
*** empty log message ***
Diffstat
-rw-r--r--ChangeLog-99b8
-rw-r--r--docs/exceptions.html243
2 files changed, 251 insertions, 0 deletions
diff --git a/ChangeLog-99b b/ChangeLog-99b
index 5dd60d45c9d..4d8e1cf1858 100644
--- a/ChangeLog-99b
+++ b/ChangeLog-99b
@@ -1,3 +1,8 @@
+Fri Jan 15 03:45:46 1999 Nanbor Wang <nanbor@cs.wustl.edu>
+
+ * docs/exceptions.html: Rewrote the exception handling guildlines
+ based on ACE's try macros.
+
Fri Jan 15 01:32:55 1999 Douglas C. Schmidt <schmidt@cs.wustl.edu>
* ACE version 4.6.14 released.
@@ -23,6 +28,9 @@ Thu Jan 14 21:50:22 1999 Nanbor Wang <nanbor@cs.wustl.edu>
soon be *DEPRICATED* once we finished convert TAO to use the new
macros.
+ Please see ACE_wrappers/docs/exceptions.html for guidelines and
+ rules of using ACE's try macros.
+
Thu Jan 14 20:41:33 1999 Douglas C. Schmidt <schmidt@ace.cs.wustl.edu>
* ace/OS: Moved some code around to consolidate the getuid() and
diff --git a/docs/exceptions.html b/docs/exceptions.html
new file mode 100644
index 00000000000..c90f90970b6
--- /dev/null
+++ b/docs/exceptions.html
@@ -0,0 +1,243 @@
+<!DOCTYPE HTML SYSTEM
+"http://www.w3.org/pub/WWW/MarkUp/Cougar/Cougar.dtd">
+<!-- $Id$ -->
+<html> <head>
+<title>Using ACE try macros for CORBA programming</title>
+</head>
+
+<body>
+<h1>Using ACE try macros for CORBA programming</h1>
+
+CORBA::Environment provides a way for exception handling when native
+c++ exception handling is unavailable or undesirable. However, writing
+portable code for both (with and without) native exception handling
+capability is very hairy. ACE provides a set of macros to help dealing
+with the chaos.
+
+<h3>In a Nutshell</h3>
+
+This section explains some simple rules of writing programs for
+platforms with and without native exception support using ACE's try
+macros.
+
+<ol>
+ <li><em>Name of CORBA::Environment variable</em><br>
+ A function that may throw a CORBA::Exception needs a
+ CORBA::Environment variable to pass up exceptions and to gather
+ exceptions from functions it called. By default, ACE try macros
+ assume the variable is named <code>ACE_TRY_ENV</code>.
+ <code>ACE_TRY_ENV</code> itself is also a macro which can be
+ redefined. If you are using TAO, more likely than not, you
+ don't have to worry about redefining this macro because TAO
+ is written to use ACE try macros. For example, you should
+ define your functions as,
+ <pre>
+ int AN_OBJ::foobar (int a, int b, CORBA_Environment &ACE_TRY_ENV);
+ </pre>
+ and within the function, call other functions that might throw
+ exceptions like,
+ <pre>
+ another_obj->func_name (x, y, ACE_TRY_ENV);
+ </pre><p>
+
+ As mentioned, you can redefine the name of the variable to
+ something else to avoid name clashing. Alternatively, there's
+ another macro (<code>ACE_ADOPT_CORBA_ENV</code>) that allow you
+ to use another variable name as the default CORBA::Environment
+ <em>within</em> a function.
+
+ <li><em>Throwing exceptions:</em><br>
+ Use <code>ACE_THROW</code> and <code>ACE_THROW_RETURN</code> to
+ throw exceptions. They should never be used withing a try
+ block.<p>
+
+ <li><em>Propagating exceptions:</em><br>
+ To simulate native exceptions on platforms without native
+ exception handling, <em>every</em> single function call that may
+ throw exceptions must be followed by <code>ACE_CHECK</code> or
+ <code>ACE_CHECK_RETURN</code>. Notice that you should always
+ follow the outter most <code>ACE_ENDTRY</code> with
+ <code>ACE_CHECK</code> or <code>ACE_CHECK_RETURN</code> because
+ there might be uncaught exception.<p>
+
+ You should pass <code>ACE_TRY_ENV</code> to these functions.<p>
+
+ Be very careful not to combine exception throwing functions in
+ one statement like this:
+ </pre>
+ x = obj1->callme (ACE_TRY_ENV) + obj2->dare_me (ACE_TRY_ENV);
+ ACE_CHECK;
+ <pre>
+ This example may work differently when native exception handling
+ is enabled/disabled.<p>
+
+ <li><em>Catching exceptions:</em><br>
+ Use <code>ACE_TRY</code> to catch exceptions if there's an
+ <code>ACE_TRY_ENV</code> available. Otherwise, use
+ <code>ACE_TRY_NEW_ENV</code>. If there are more than one try
+ blocks in a function, use <code>ACE_TRY_EX</code> for all
+ subsequence try blocks to avoid name clashing of labels.<p>
+ <ul>
+ <li>Within a <code>ACE_TRY</code> block, use the variable
+ <code>ACE_TRY_ENV</code> to pass down the
+ <code>CORBA_Environment</code> (see <a
+ href="#try_env">this</a> example.) <p>
+
+ <li>Follow <em>every</em> exception throwing function with
+ <code>ACE_TRY_CHECK</code>, including inner
+ <code>ACE_ENDTRY</code>.<p>
+
+ <li>Use <code>ACE_CATCH</code> to catch exceptions of certain
+ type. <p>
+
+ <li><code>ACE_CATCHANY</code> catches <em>any</em> exceptions
+ of type <code>CORBA_Exception</code>.<p>
+
+ <li>Use <code>ACE_RETHROW</code> to rethrow the same exception
+ within a <code>ACE_CATCH</code> or
+ <code>ACE_CATCHANY</code> block.<p>
+
+ <li>A <code>ACE_TRY</code> block must be terminated with a
+ <code>ACE_ENDTRY</code> statement.<p>
+
+ <li>Throw an exception within a <code>ACE_TRY</code> block or
+ <code>ACE_CATCH</code> block using <a href="#try_throw">
+ <code> ACE_TRY_THROW</code></a>.<p>
+ </ul><p>
+
+</ol>
+
+<h3>Examples</h3>
+
+Refer to <a href="../ace/CORBA_macros.h"><code>
+$ACE_ROOT/ace/CORBA_macros.h</code></a> for complete definitions of
+macros discussed here.
+
+<ul>Sample exception catching:
+<pre>
+ ACE_TRY
+ {
+ some_operation (arg1, arg2, ACE_TRY_ENV);
+ ACE_TRY_CHECK;
+
+ .
+ .
+ if (whatever)
+ ACE_TRY_THROW (CORBA::BadParam);
+
+ some_other_operation (arg1, arg2, arg3, ACE_TRY_ENV);
+ ACE_TRY_CHECK;
+ }
+ ACE_CATCH (CORBA_some_exception, ex)
+ {
+ // error handling.
+ if (still_has_error)
+ ACE_TRY_THROW (CORBA::NOWAY);
+ }
+ ACE_CATCHANY
+ {
+ // error handling.
+ // then rethow the exception.
+ ACE_RETHROW;
+ }
+ ACE_ENDTRY;
+ ACE_CHECK;
+</pre><br>
+
+ <li><code>ACE_TRY</code> and also declares a label (so do
+ <code>ACE_TRY_NEW_ENV</code>. To avoid defining the
+ same label multiple times within a function, use
+ <code>ACE_TRY_EX</code> with different labels for different try
+ blocks instead. For example,<br>
+
+<pre>
+ ACE_TRY_EX (block_1)
+ {
+ some_operation (arg1, arg2, ACE_TRY_ENV);
+ ACE_TRY_CHECK_EX (block_1);
+
+ some_other_operation (arg1, arg2, arg3, ACE_TRY_ENV);
+ ACE_TRY_CHECK_EX (block_1);
+ }
+ ACE_CATCH (CORBA_some_exception, ex)
+ {
+ // error handling.
+ }
+ ACE_CATCHANY
+ {
+ // error handling.
+ }
+ ACE_ENDTRY;
+ ACE_CHECK_RETURN (-1);
+
+ // Some other operation here
+ // .
+ // .
+ // .
+ // .
+
+ ACE_TRY_EX (block_2)
+ {
+ foo (arg, ACE_TRY_ENV);
+ ACE_TRY_CHECK_EX (block_2);
+
+ bar (arg1, arg2, ACE_TRY_ENV);
+ ACE_TRY_CHECK_EX (block_2);
+ }
+ ACE_CATCH (CORBA_some_exception, ex)
+ {
+ // error handling.
+ }
+ ACE_CATCHANY
+ {
+ // error handling.
+ }
+ ACE_ENDTRY;
+ ACE_CHECK_RETURN (-1);
+</pre><p>
+
+ <li>Be <em>VERY</em> wary of <code>ACE_CATCHALL</code>. It catches
+ exceptions of any type. If your program depends on it, then,
+ more often than not, there're something wrong with it.<p>
+
+ <li>Instead of depending on <code>ACE_CATCHALL</code>, use
+ <code>auto_prt</code> style mechanism to prevent memory leaks
+ from exceptions.<p>
+</ul>
+
+<h3>General Guidelines of Exceptions</h3>
+<ul>
+ <li>Don't catch an exception just to rethrow it. Exceptions cost
+ you performance.<p>
+
+ <li>When exceptions occur, make sure an object's is still in
+ a valid state or change to a state that can be safely
+ destructed.<p>
+
+ <li>Watch out for side effect in the expression which may cause
+ exceptions. In the following example, what should
+ <code>i</code> be if an exception does occur?<br>
+<pre>
+ ACE_TRY
+ {
+ obj[i++] = foo_bar_method (a, b, ACE_TRY_ENV);
+ }
+</pre><p>
+
+ <li>Make sure an exception doesn't cause resource leak (memory,
+ socket, ...) (hint: Use auto_ptr to avoid memory leak.)<p>
+
+ <li>Don't catch any exception that you don't know how to handle.<p>
+
+ <li>Never throw an exception from destructor (unless you know what
+ it implies.)<p>
+
+ <li>Use exceptions to provide more information about the error.<p>
+
+ <li>Rethrow a different exception only to provide <em>more</em>
+ information. Do not catch an exception just to rethrow, say,
+ <code>unknow_exception</code>.<p>
+
+</ul>
+<!--#include virtual="/~schmidt/cgi-sig.html" -->
+</body></HTML>
View Lorry Controller Status