diff options
| author | coryan <coryan@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 1999-01-18 22:47:20 +0000 |
|---|---|---|
| committer | coryan <coryan@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 1999-01-18 22:47:20 +0000 |
| commit | 0a73e227857d6edd944055cdd893d796d5075fef (patch) | |
| tree | 375c2b4fc7e9bdcca412c45e4724d3aa6bf3f825 /docs/exceptions.html | |
| parent | 40e97cc6977cbc9e431eaf09df51690b18091058 (diff) | |
| download | ATCD-0a73e227857d6edd944055cdd893d796d5075fef.tar.gz | |
General revision.
Diffstat (limited to 'docs/exceptions.html')
| -rw-r--r-- | docs/exceptions.html | 262 |
1 files changed, 164 insertions, 98 deletions
diff --git a/docs/exceptions.html b/docs/exceptions.html index c90f90970b6..21a57895020 100644 --- a/docs/exceptions.html +++ b/docs/exceptions.html @@ -1,111 +1,144 @@ -<!DOCTYPE HTML SYSTEM -"http://www.w3.org/pub/WWW/MarkUp/Cougar/Cougar.dtd"> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> <!-- $Id$ --> <html> <head> <title>Using ACE try macros for CORBA programming</title> </head> -<body> -<h1>Using ACE try macros for CORBA programming</h1> + <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. + <P>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. + </P> + <P>ACE provides a set of macros to help dealing with the chaos, + but please keep in mind that no amount of macros is going to + solve the problem perfectly. + </P> <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> + <P>This section explains some simple rules of writing programs for + platforms with and without native exception support using ACE's + try macros. + </P> + + <ol> + <li><P><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, + </P> + <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> + </pre> + <P> + and within the function, call other functions that might throw + exceptions like, + </P> + <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> + </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. + </P> + </LI> + + <li><P><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; please use <code>ACE_TRY_THROW</code> instead. + </P> + </LI + + <li><P><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> + + <P>You should pass <code>ACE_TRY_ENV</code> to these + functions. + </p> + + <P>Be very careful not to combine exception throwing functions + in one statement like this: + </P> + <pre> + x = obj1->callme (ACE_TRY_ENV) + obj2->dare_me (ACE_TRY_ENV); + ACE_CHECK; + </pre> + <P>This example may work differently when native exception + handling is enabled/disabled. + </p> + </LI> + + <li><P><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><P>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> + + <li><P>Follow <em>every</em> exception throwing function with + <code>ACE_TRY_CHECK</code>, including inner + <code>ACE_ENDTRY</code>. + </p> + </LI> + + <li><P>Use <code>ACE_CATCH</code> to catch exceptions of certain + type. + </p> + </LI> + + <li><P><code>ACE_CATCHANY</code> catches <em>any</em> exceptions + of type <code>CORBA_Exception</code>. + </p> + </LI> + + <li><P>Use <code>ACE_RETHROW</code> to rethrow the same exception + within a <code>ACE_CATCH</code> or + <code>ACE_CATCHANY</code> block. + </p> + </LI> + + <li><P>A <code>ACE_TRY</code> block must be terminated with + a <code>ACE_ENDTRY</code> statement. + </p> + </LI> + + <li><P>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> + </LI> + </LI> + </ul> + </ol> <h3>Examples</h3> @@ -225,7 +258,8 @@ macros discussed here. </pre><p> <li>Make sure an exception doesn't cause resource leak (memory, - socket, ...) (hint: Use auto_ptr to avoid memory leak.)<p> + socket, ...) (hint: Use auto_ptr to avoid memory leak, + and ACE_Guard for locks.)<p> <li>Don't catch any exception that you don't know how to handle.<p> @@ -238,6 +272,38 @@ macros discussed here. information. Do not catch an exception just to rethrow, say, <code>unknow_exception</code>.<p> +<H3>Caveats</H3> + + <P>As we already mentioned no set of macros can cover all cases + and preserve the semantics between native C++ exceptions and the + <CODE>CORBA::Environment</CODE> based mapping. + Some of the problems that our macros are described below: + <P> + + <UL> + <LI><P>Using the macros in loops can produce problems with + <CODE>break</CODE> and <CODE>continue</CODE> statements, for + example: + </P> + <PRE> +for (int i = 0; i < 10; ++i) +{ + ACE_TRY + { + if (x[i] == 0) + continue; // will *not* work + if (x[i] == -1) + break; // will *not* work either + } + ACE_CATCH (CORBA::Exception, ex) + { + } + ACE_ENDTRY; +} +</PRE> + </UL> + + </ul> <!--#include virtual="/~schmidt/cgi-sig.html" --> </body></HTML> |