diff options
Diffstat (limited to 'TAO/docs/exceptions.html')
-rw-r--r-- | TAO/docs/exceptions.html | 314 |
1 files changed, 0 insertions, 314 deletions
diff --git a/TAO/docs/exceptions.html b/TAO/docs/exceptions.html deleted file mode 100644 index da2d41f7541..00000000000 --- a/TAO/docs/exceptions.html +++ /dev/null @@ -1,314 +0,0 @@ -<!DOCTYPE HTML SYSTEM -"http://www.w3.org/pub/WWW/MarkUp/Cougar/Cougar.dtd"> -<!-- $Id$ --> -<html> <head> -<title>Writing exception safe codes</title> -</head> - -<body> -<h1>Writing exception safe codes</h1> - -TAO can be use on platforms with/without native exception support. -However, there are certain guidelines that need to be followed in -order for it to work on both platforms. - -<h3>In a Nutshell</h3> - -This section explains some simple rules of writing programs for -platforms with and without native exception support using TAO's try -macros. - -<ol> - <li><em>Function definition:</em><br> - A function that throws exceptions or calls other exception - throwing functions must have an argument of reference of - <code>CORBA_Environment</code> for exceptions be passed back - thru it. This arguemnt should <em>always</em> be named - <code>TAO_IN_ENV</code> (which means the passed in environment,) - and has a default value of - <code>CORBA_Environment::default_environment ()</code>. For - example,<p> - - <pre> - int foobar (int a, int b, CORBA_Environment &TAO_IN_ENV = - CORBA_Environment::default_environment); - </pre><p> - - <li><em>Throwing exceptions:</em><br> - Use <code>TAO_THROW</code> and <code>TAO_THROW_RETURN</code> to - throw exceptions. - - <li><em>Propagating exceptions:</em><br> - To simulate native exceptions on platforms without native - exceptions, <em>every</em> single function call that may throw - exceptions must be followed by <code>TAO_CHECK_RETURN</code> or - <code>TAO_CHECK_RETURN_VOID</code>.<p> - - You should pass <code>TAO_IN_ENV</code> to these functions.<p> - - Be very careful not to combine calls to several exception - throwing functions in one statement.<p> - - <li><em>Catching exceptions:</em><br> - Use <code>TAO_TRY</code> and buddies to catch exceptions.<p> - <ul> - <li>Within a <code>TAO_TRY</code> block, use the variable - <code>TAO_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>TAO_CHECK_ENV</code>. <p> - - <li>Use <code>TAO_CATCH</code> to catch exceptions of certain - type. <p> - - <li><code>TAO_CATCHANY</code> catches <em>any</em> exceptions - of type <code>CORBA_Exception</code>.<p> - - <li>Use <code>TAO_RETHROW</code> to rethrow the same exception - within a <code>TAO_CATCH</code> or - <code>TAO_CATCHANY</code> block.<p> - - <li>A <code>TAO_TRY</code> block must be terminated with a - <code>TAO_ENDTRY</code> statement.<p> - - <li>Throw an exception within a <code>TAO_TRY</code> block - using <a href="#try_throw"><code>TAO_TRY_THROW</code></a><p> - - <li>Notice that at the moment, <code>TAO_TRY</code> macros do - not propogate the exception up if one is not caught.<p> - - </ul><p> - - <li>Avoid using macros that require to specify the environment used - like, <code>TAO_THROW_ENV_RETURN</code>, - <code>TAO_CHECK_ENV_RETURN</code> and so on. They will be - depricated in the future. -</ol> - -<h3>Details</h3> - -Refer to <code>$TAO_ROOT/tao/try_macros.h</code> for complete -definitions of macros discussed here. - -<ul> - <li>Use <code>TAO_THROW</code>, <code>TAO_THROW_ENV</code>, - <code>TAO_THROW_RETURN</code>, <code>TAO_THROW_ENV_RETURN</code> - to throw exceptions. <code>TAO_THROW</code> and - <code>TAO_THROW_RETURN</code> assume that the name of the - <code>CORBA_Environment</code> variable used to pass back the - exception is called <code>_env</code>. Use - <code>TAO_THROW_ENV</code> and <code>TAO_THROW_ENV_RETURN</code> - to pass back thru the <code>CORBA_Environment</code> variable - specified. (Also see: <a href="#try_throw">Throwing exceptions - within try blocks.</a>)<p> - - <li><a name="try_env"></a>Use <code>TAO_TRY</code>, - <code>TAO_CHECK_ENV</code>, <code>TAO_CATCH</code>, - <code>TAO_CATCHANY</code>, and <code>TAO_ENDTRY</code> - macros. For example:<br> - -<pre> - TAO_TRY - { - some_operation (arg1, arg2, TAO_TRY_ENV); - TAO_CHECK_ENV; - - some_other_operation (arg1, arg2, arg3, TAO_TRY_ENV); - TAO_CHECK_ENV; - } - TAO_CATCH (CORBA_some_exception, ex) - { - // error handling. - } - TAO_CATCHANY - { - // error handling. - } - TAO_ENDTRY; -</pre><br> - - Since a lot of compilers/platforms still don't handle native - exceptions correctly, TAO doesn't use exceptions on these - platforms and tend to check the returning environment. When - these programs move to platforms that support native exceptions, - they stop working.<p> - - <li><code>TAO_TRY</code> defines a new - <code>CORBA_Environment</code> called TAO_TRY_ENV and use it to - pass down the functions it guards against. If you want to reuse - the <code>CORBA_Environment</code> that's alreday defined in the - scope <code>TAO_TRY</code> resides, you can use - <code>TAO_TRY_VAR</code> to achieve that.<p> - - <li><code>TAO_TRY</code> also declares a label. To avoid defining the - same label multiple times within a function, use - <code>TAO_TRY_EX</code>, <code>TAO_CHECK_ENV_EX</code> with - different labels for different try blocks instead. For - example,<br> - -<pre> - TAO_TRY_EX (block_1) - { - some_operation (arg1, arg2, TAO_TRY_ENV); - TAO_CHECK_ENV_EX (block_1); - - some_other_operation (arg1, arg2, arg3, TAO_TRY_ENV); - TAO_CHECK_ENV_EX (block_1); - } - TAO_CATCH (CORBA_some_exception, ex) - { - // error handling. - } - TAO_CATCHANY - { - // error handling. - } - TAO_ENDTRY; - - // Some other operation here - // . - // . - // . - // . - - TAO_TRY_EX (block_2) - { - foo (arg, TAO_TRY_ENV); - TAO_CHECK_ENV_EX (block_2); - - bar (arg1, arg2, TAO_TRY_ENV); - TAO_CHECK_ENV_EX (block_2); - } - TAO_CATCH (CORBA_some_exception, ex) - { - // error handling. - } - TAO_CATCHANY - { - // error handling. - } - TAO_ENDTRY; -</pre><p> - - <a name="try_throw"></a> - <li>Notice that you need to use <code>TAO_TRY_THROW</code> and - <code>TAO_TRY_THROW_EX</code> when throwing exceptions within - the try block. Without using it, the exception won't be caught - by the try block, which is not how native exceptions work.<p> - - <li>Follow each operation that may throw an exception with - <code>TAO_CHECK_ENV</code> or <code>TAO_CHECK_ENV_EX</code>. - This is required for simulated exceptions to break out of - current flow of control into <code>TAO_CATCH</code> - sections. Although it is not required to put an - <code>TAO_CHECK_ENV</code> or an <code>TAO_CHECK_ENV_EX</code> - after the last operation, it is much cleaner to always put it - there and avoid further errors when you need add more stuff - after that.<p> - - <li>TAO functions use a <code>CORBA_Environment</code> argument to - pass in/out the simulated exceptions. By default, this argument - is named "<code>_env</code>" (which is what TAO_IDL generated - code uses.) Use <code>TAO_THROW</code> or - <code>TAO_THROW_RETURN</code> to throw an exception. However, - if a function uses a different name to pass back the CORBA - environment, you'll need to use <code>TAO_THROW_ENV</code> or - <code>TAO_THROW_ENV_RETURN</code> and specify the name of the - variable used to pass back the CORBA environment.<p> - - <li>To rethrow an exception after catching it, use - <code>TAO_RETHROW_RETURN</code> or - <code>TAO_RETHROW_RETURN_VOID</code>. But if you are reusing - the same <code>CORBA::Environment</code> variable of the - function in the try block, use - <code>TAO_RETHROW_SAME_ENV_RETURN</code> and - <code>TAO_RETHROW_SAME_ENV_RETURN_VOID</code> instead.<p> - - <li>Follow each statement that throws exceptions with - <code>TAO_CHECK_ENV_RETURN</code>, - <code>TAO_CHECK_ENV_RETURN_VOID</code> when these exceptions are - not to be caught in the current subroutine. Likewise, - <code>TAO_CHECK_ENV_PRINT_RETURN</code> and - <code>TAO_CHECK_ENV_PRINT_RETURN_VOID</code> pass back an - exception after printing out the content. Notice that the - printing will not work on platforms where native exceptions are - supported. If you have to print out exceptions, you <em>have - to</em> catch them. All these macros cannot and should not be - used in a <code>TRY</code> block.<p> - - <li><code>TAO_GUARD_THROW</code>, - <code>TAO_GUARD_THROW_RETURN</code>, - <code>TAO_READ_GUARD_THROW</code>, - <code>TAO_READ_GUARD_THROW_RETURN</code>, - <code>TAO_WRITE_GUARD_THROW</code>, and - <code>TAO_WRITE_GUARD_THROW_RETURN</code> try to acquire a lock - and throw the specified exception when it fails to acquire the - lock.<p> - - <li>Notice that <code>TAO_CATCHANY</code> catches <em>any</em> - <code>CORBA_Exception</code> or its subclasses. This limited - catch behavior makes TAO programs behave the same on platforms - with or without native exceptions. If there're needs to catch - all native exceptions in your program, use - <code>TAO_CATCHALL</code> instead. <p> - - <li>Be <em>VERY</em> wary of <code>TAO_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>Use <code>auto_prt</code> type mechanism to prevent memory leaks - from exceptions.<p> - - <li>Don't catch an exception just to rethrow it. Exceptions cost - you performance.<p> - - <li>Current implementation of <code>TAO_TRY/TAO_CATCH</code> macros - do not propagate a exception up if it is not caught. (So, - you'll have to catch all exceptions with a - <code>TAO_CATCHANY</code> and rethrow it, which contradicts the - previous guideline. ;( )<p> - -</ul> - -<h2>TO-DO</h2> -<ol> - <li>Automatic rethrow simpulated exceptions if not caught? - <li>must check if the same exception can be caught twice on - compilers without c++ exceptions. -</ol> - -<h3>General Guidelines of Exceptions</h3> -<ul> - <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> - TAO_TRY - { - obj[i++] = foo_bar_method (a, b, TAO_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> |