diff options
Diffstat (limited to 'docs/exceptions.html')
| -rw-r--r-- | docs/exceptions.html | 243 |
1 files changed, 0 insertions, 243 deletions
diff --git a/docs/exceptions.html b/docs/exceptions.html deleted file mode 100644 index c90f90970b6..00000000000 --- a/docs/exceptions.html +++ /dev/null @@ -1,243 +0,0 @@ -<!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> |