Merge branch 'master' into jwi-bcc64xsingletonwarning
[ACE_TAO.git] / ACE / docs / exceptions.html
blob3ea5b3b4b42e6834460481ec8fad823c9b0f54a9
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <!-- -->
3 <html> <head>
4 <title>Using ACE Exception Handling Macros to Enhance CORBA Portability</title>
5 </head>
7 <body text="#000000" link="#0000ff" vlink="#cc0000" bgcolor="#ffffff">
8 <Hr><P>
9 <h3>Using ACE Exception Handling Macros to Enhance CORBA Portability</h3>
11 <P>CORBA <CODE>Environment</CODE> arguments provide a way to handle
12 exceptions when native c++ exception handling is unavailable or
13 undesirable. However, writing portable code using both native C++
14 exception handling and <CODE>CORBA::Environment</CODE> objects is very
15 hard. If you plan to write portable code that must run on platforms
16 that do not have native C++ exceptions, therefore, we recommend you
17 use the ACE exception macros. This document explains how these macros
18 can help alleviate much of the accidental complexity. However, keep
19 in mind macros cannot solve all problems perfectly. </P>
21 <P>Before reading the rest of this document, we recommend you check
22 out pages 307 through to 322 in the book, <A
23 HREF="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-37927-9&ptype=0">Advanced
24 Corba Programming with C++</A> by <A
25 HREF="http://www.triodia.com/staff/michi-henning.html">Michi
26 Henning</A> & <A HREF="http://www.iona.com/hyplan/vinoski/">Steve
27 Vinoski</A>. Likewise, we recommend that you read the Error Handling chapter from the
28 <A HREF="http://www.theaceorb.com/product/">TAO Developer's Guide</A>.
30 <P><HR><P>
31 <h3>Table of Contents</h3>
32 <ul>
33 <li><a href="#nutshell">ACE Try Macros in a Nutshell</a>
34 <li><a href="#examples">Examples</a>
35 <li><a href="#general">General Guidelines for Exception Handling</a>
36 <li><a href="#transition">Transition from ACE_TRY_ENV usage to the
37 ACE_ENV_ARG macros</a>
38 <li><a href="#caveats">Some Caveats</a>
39 </ul>
41 <HR><P>
42 <h3><a name="nutshell">ACE Exception Macros in a Nutshell</h3>
44 <P>This section explains some simple rules of writing programs for
45 platforms with and without native exception support using ACE's
46 exception macros.
47 </P>
48 <P>ACE exception macros are modelled like C++ language exceptions and
49 can be used like them, but with a small difference. These macros
50 rely on the CORBA::Environment variable to handle exceptions
51 on platforms that do not support exception
52 handling. (Please note that native exceptions can be turned on
53 or off at COMPILE time as an option to your make)
54 The exception macros have been modelled with some extra rules to
55 ensure this works even on
56 platforms without native exception support. See some <a
57 href="#examples">quick examples</a> on how to use ACE exception
58 macros.
59 </P>
60 <ol>
61 <li><P><em>Declaration of CORBA::Environment Parameter at Methods</em><br>
62 On platforms lacking native exceptions, all CORBA methods take an
63 extra parameter added at the end of their argument list. This
64 last parameter holds the CORBA::Environment variable.
65 However, on systems with native exceptions, no such extra method
66 parameter is added.<br>
67 In order for both configurations to work with the same source code,
68 following macros are defined. In native exception configurations,
69 they all resolve to <em>empty</em>.</p>
70 <ul>
71 <li><p><em>ACE_ENV_ARG_DECL</em></p>
72 in the pseudo exception configuration resolves to
73 <pre>
74 , CORBA::Environment ACE_TRY_ENV
75 </pre>
76 It is used for declaring the extra Environment parameter
77 at CORBA methods that take one or more regular parameters.
78 The fact that the comma is part of the macro substitution
79 caters for the hiding of this added argument when native
80 exceptions are used. However, by the same virtue its
81 usage is a bit peculiar -<br>
82 Example: a CORBA IDL defined method
83 <pre>
84 void mymethod (in boolean b);
85 </pre>
86 may be declared as follows in C++:
87 <pre>
88 void mymethod (CORBA::Boolean b ACE_ENV_ARG_DECL);
89 </pre>
90 Notice the missing comma before the ACE_ENV_ARG_DECL.
91 This notation is necessary because when using native exceptions,
92 also the presence of the comma before the (non-existent)
93 CORBA::Environment parameter must be hidden.</p>
94 </li>
95 <li><p><em>ACE_ENV_SINGLE_ARG_DECL</em></p>
96 is similar to <code>ACE_ENV_ARG_DECL</code>, but is used when
97 the method takes no other parameters. It is necessary as a
98 separate macro because it does not contain the leading comma
99 that <code>ACE_ENV_ARG_DECL</code> does.
100 Example: a CORBA IDL defined method
101 <pre>
102 void mymethod ();
103 </pre>
104 may look like this in C++:
105 <pre>
106 void mymethod (ACE_ENV_SINGLE_ARG_DECL);
107 </pre>
108 <li><p><em>ACE_ENV_ARG_DECL_WITH_DEFAULTS</em>,
109 <li><em>ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS</em></p>
110 are similar to the above two macros but add a default value
111 to the parameter declaration. In case of TAO, the default value
112 is <code>TAO_default_environment()</code>.<p>
113 Notice that these macros are only used at the declaration
114 of methods (usually in header files), not at their definition
115 (usually in implementation files.) At the definition,
116 instead use the corresponding macro without "_WITH_DEFAULTS".
117 Example: the CORBA IDL defined method
118 <pre>
119 void mymethod ();
120 </pre>
121 in the C++ header file looks like this:
122 <pre>
123 void mymethod (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS);
124 </pre>
125 and in the C++ implementation file may look something like:
126 <pre>
127 void mymethod (ACE_ENV_SINGLE_ARG_DECL)
129 // ...
131 </pre>
132 </ul>
134 <br>
135 </li>
137 <li><P><em>Passing the CORBA::Environment Parameter into Method Calls</em><br>
138 Now that we've seen how to declare methods with Environment
139 parameters, let's see how to invoke such methods.</p>
140 <ul>
141 <li><p><em>ACE_ENV_ARG_PARAMETER</em></p>
142 in the pseudo exception configuration resolves to
143 <pre>
144 , ACE_TRY_ENV
145 </pre>
146 and is written as the last parameter of a method call that takes
147 one or more regular parameters. Again we need to omit the
148 comma that would normally precede this last parameter, as the
149 comma is already part of the macro definition. For example,
150 the CORBA IDL method
151 <pre>
152 void mymethod (in boolean b);
153 </pre>
154 would be invoked as follows:
155 <pre>
156 some_var.mymethod (bparam ACE_ENV_ARG_PARAMETER);
157 </pre>
158 </ul>
160 <ul>
161 <li><p><em>ACE_ENV_SINGLE_ARG_PARAMETER</em></p>
162 is similar to <code>ACE_ENV_ARG_PARAMETER</code> but is used
163 for calling methods that don't take any regular parameters.
164 Our example of a CORBA IDL method
165 <pre>
166 void mymethod ();
167 </pre>
168 we would invoke as follows:
169 <pre>
170 some_var.mymethod (ACE_ENV_SINGLE_ARG_PARAMETER);
171 </pre>
172 </ul>
173 <br>
174 </li>
176 <li><P><em>Definition of the CORBA::Environment variable </em><br>
177 We have seen how to declare methods with the CORBA::Environment
178 parameter, and how to invoke such methods. However, where does
179 the variable to pass into methods as the CORBA::Environment
180 parameter come from in the first place?</p>
181 <P>An environment variable can be defined in the needed scope
182 (for example, in the main program, or in a more local scope)
183 by the statement</p>
184 <pre>
185 ACE_DECLARE_NEW_CORBA_ENV;
186 </pre>
187 <P>You can then invoke the methods on the servant from the client
188 side as
189 <pre>
190 object_reference->func_name (x, y ACE_ENV_ARG_PARAMETER);
191 </pre>
193 Even if you are interested in making calls within the client
194 side, you can define your method like this
195 <pre>
196 int AN_OBJ::foobar (int a, int b ACE_ENV_ARG_DECL);
197 </pre>
199 <li><P><em>Throwing exceptions:</em><br>
200 Use <code>ACE_THROW</code> and <code>ACE_THROW_RETURN</code> to
201 throw exceptions. They should never be used within a try
202 block; please use <code>ACE_TRY_THROW</code> instead.
203 </P>
204 </LI>
206 <li><P><em>Propagating exceptions:</em><br>
207 To simulate native exceptions on platforms without native
208 exception handling, <em>every</em> function call that may
209 throw exceptions must be followed by <code>ACE_CHECK</code> or
210 <code>ACE_CHECK_RETURN</code>.</p>
212 <p><a name="exc-func">Exception-throwing functions include the
213 following categories:</p>
215 <ol>
216 <li><p>Any function that takes a
217 <code>CORBA_Environment</code> argument.</p>
218 </li>
220 <li><p><code>ACE_NEW_THROW_EX</code>. Notice that you
221 <em>should not</em> use <code>ACE_NEW_THROW</code>,
222 <code>ACE_NEW_THROW_RETURN</code>,
223 <code>ACE_NEW_TRY_THROW</code> anymore because they don't
224 work right with ACE try macros. Instead, use
225 <code>ACE_NEW_THROW</code> with appropriate ACE_CHECK*
226 macros.</p>
227 </li>
229 <li><P><code>ACE_GUARD_THROW_EX</code>,
230 <code>ACE_READ_GURAD_THROW_EX</code>, and
231 <code>ACE_WRITE_THROW_EX</code>.
233 <li><p><code>ACE_TRY</code> blocks. Follow every
234 <code>ACE_ENDTRY</code> with appropriate ACE_CHECK*
235 macros.</p>
236 <li>
237 </ol>
239 <P>You should pass <code>ACE_TRY_ENV</code> to these
240 functions.
241 </p>
243 <P>Be very careful not to combine exception throwing functions
244 in one statement like this:
245 </P>
246 <pre>
247 x = obj1->callme (ACE_ENV_SINGLE_ARG_PARAMETER)
248 + obj2->dare_me (ACE_ENV_SINGLE_ARG_PARAMETER);
249 ACE_CHECK;
250 </pre>
251 <P>This example may work differently when native exception
252 handling is enabled/disabled.
253 </p>
254 </LI>
256 <li><P><em>Catching exceptions:</em><br>
257 Use <code>ACE_TRY</code> to catch exceptions if there's an
258 <code>ACE_TRY_ENV</code> available. Otherwise, you should use
259 <code>ACE_DECLARE_NEW_CORBA_ENV</code> to create one at
260 <em>proper</em> scope. The use of
261 <code>ACE_TRY_NEW_ENV</code> is considered depricated because it
262 can't deal with the case when you have multiple <code>TRY</code>
263 blocks in the scope of <code>ACE_TRY_NEW_ENV</code>. If there are
264 more than one try blocks in a function, use <code>ACE_TRY_EX</code>
265 for all subsequence try blocks to avoid name clashing of labels.
266 </p>
267 <ul>
268 <li><P>Within a <code>ACE_TRY</code> block, use the variable
269 <code>ACE_TRY_ENV</code> to pass down the
270 <code>CORBA_Environment</code> (see <a
271 href="#try_env">this</a> example.)
272 </p>
273 </LI>
275 <li><P>Follow <em>every</em> exception throwing function with
276 <code>ACE_TRY_CHECK</code>. If you are using a TRY block
277 within another try block add a <code>ACE_TRY_CHECK</code>
278 at the end of this TRY block ie. after
279 <code>ACE_ENDTRY</code>.
280 </p>
281 </LI>
283 <li><P>Use <code>ACE_CATCH</code> to catch exceptions of certain
284 type.
285 </p>
286 </LI>
288 <li><P><code>ACE_CATCHANY</code> catches <em>any</em> exceptions
289 of type <code>CORBA_Exception</code>. The caught
290 exception is stored in a variable call
291 <code>ACE_ANY_EXCEPTION</code>.
292 </p>
293 </LI>
295 <li><p><code>ACE_CATCHALL</code> emulate the <code>catch
296 (...)</code> c++ statement. It is identical to
297 <code>ACE_CATCHANY</code> on platforms without native
298 exception support. You can not access the caught
299 exception within the <code>ACE_CATCHALL</code> block.</p>
301 <li><P>Use <code>ACE_RE_THROW</code> to rethrow the same exception
302 within a <code>ACE_CATCH</code> or
303 <code>ACE_CATCHANY</code> block.
304 </p>
305 </LI>
307 <li><P>A <code>ACE_TRY</code> block must be terminated with
308 a <code>ACE_ENDTRY</code> statement.
309 </p>
310 </LI>
312 <li><P>Throw an exception within a <code>ACE_TRY</code>
313 block or <code>ACE_CATCH</code> block using
314 <a href="#ace_try"><code>ACE_TRY_THROW</code></a>.
315 </p>
316 </LI>
317 </ul>
318 </li>
320 <li><p><em>Printing out exceptions.</em> Use <code>ACE_PRINT_EXCEPTION
321 (EX,INFO)</code> to print out an exception. The macro takes two
322 arguments, a reference to an exception (EX) and a <code>char
323 *</code> string (INFO) which provides more information on the
324 exception. Since there's no portable way to print out
325 exceptions, you can redefine ACE_PRINT_EXCEPTION to fit your
326 need (or define it to null.) <em>You should always print out
327 the exception itself, not the CORBA_Environment that carries the
328 exception.</em></p>
329 </li>
331 <li><P><em>Name of CORBA::Environment variable</em><br>
332 A function that may throw a CORBA::Exception needs a
333 CORBA::Environment variable to pass up exceptions (to throw in
334 the C++ sense) and to gather (catch () in the C++ sense)
335 exceptions from functions it called. By default, ACE exception
336 macros assume that the variable is named <code>ACE_TRY_ENV</code>.
337 <code>ACE_TRY_ENV</code> itself is also a macro which can be
338 redefined.
339 </pre>
342 You can redefine the name of the variable to
343 something else to avoid name clashing. Alternatively, there's
344 another macro (<code>ACE_ADOPT_CORBA_ENV</code>) that allow you
345 to use another variable name as the default CORBA::Environment
346 <em>within</em> a function.
347 </P>
348 </LI>
350 </ol>
352 <HR><P>
353 <h3>Examples</h3><a name="examples">
355 Refer to <a href="../ace/CORBA_macros.h"><code>
356 $ACE_ROOT/ace/CORBA_macros.h</code></a> for complete definitions of
357 macros discussed here.
359 <ul>Examples on using ACE try macros:
360 <li><p>
361 <pre>
362 <a name="try_env">
363 ACE_TRY // Use ACE_DECLARE_NEW_CORBA_ENV to create ACE_TRY_ENV
364 // if you got undefined symbol warning here.
366 some_operation (arg1, arg2 ACE_ENV_ARG_PARAMETER);
367 ACE_TRY_CHECK;
371 if (whatever)
372 ACE_TRY_THROW (CORBA::BAD_PARAM ());
374 some_other_operation (arg1, arg2, arg3 ACE_ENV_ARG_PARAMETER);
375 ACE_TRY_CHECK;
377 <a name="ace_try">
378 ACE_CATCH (CORBA_some_exception, ex)
380 // error handling.
381 if (still_has_error)
382 ACE_TRY_THROW (CORBA::NOWAY ());
384 ACE_CATCHANY
386 // error handling.
387 // then rethow the exception.
388 ACE_RE_THROW;
390 ACE_ENDTRY;
391 ACE_CHECK;
392 </pre>
393 </p>
394 </li>
396 <li><p><code>ACE_TRY</code> and also declares a label for internal
397 use. To avoid defining the same label multiple times within a
398 function, use <code>ACE_TRY_EX</code> with different labels for
399 different try blocks instead. For example,<br>
401 <pre>
402 ACE_TRY_EX (block_1)
404 some_operation (arg1, arg2 ACE_ENV_ARG_PARAMETER);
405 ACE_TRY_CHECK_EX (block_1);
407 some_other_operation (arg1, arg2, arg3 ACE_ENV_ARG_PARAMETER);
408 ACE_TRY_CHECK_EX (block_1);
410 ACE_CATCH (CORBA_some_exception, ex)
412 // error handling.
414 ACE_CATCHANY
416 // error handling.
418 ACE_ENDTRY;
419 ACE_CHECK_RETURN (-1);
421 // Some other operation here
422 // .
423 // .
424 // .
425 // .
427 ACE_TRY_EX (block_2)
429 foo (arg ACE_ENV_ARG_PARAMETER);
430 ACE_TRY_CHECK_EX (block_2);
432 bar (arg1, arg2 ACE_ENV_ARG_PARAMETER);
433 ACE_TRY_CHECK_EX (block_2);
435 ACE_CATCH (CORBA_some_exception, ex)
437 // error handling.
439 ACE_CATCHANY
441 // error handling.
443 ACE_ENDTRY;
444 ACE_CHECK_RETURN (-1);
445 </pre>
446 </p>
448 <li><p>You may want to make a different series of calls after you
449 encounter/catch an exception. Here is what we recommend.
451 <pre>
452 ACE_TRY
454 // Calls that can raise an exception
455 some_call1 (arg1, arg2 ACE_ENV_ARG_PARAMETER);
456 ACE_TRY_CHECK;
460 ACE_TRY_CHECK;
462 ACE_CATCH (CORBA_some_exception, ex)
464 // Caught an exception, so we need to make some other calls
465 // to continue..
467 ACE_TRY_EX (block1) // basically a label
469 some_other_call1 (arg1,.. ACE_ENV_ARG_PARAMETER);
470 ACE_TRY_CHECK_EX (block1);
472 ACE_CATCH (CORBA_some_other_exception, ex1)
474 // Handle the exception here..
476 ACE_ENDTRY;
477 ACE_CHECK_RETURN (-1); // Needed to catch uncaught exceptions
479 ACE_ENDTRY;
480 ACE_CHECK_RETURN (-1);
481 </pre>
482 </p>
484 <li><p>Be <em>VERY</em> wary of <code>ACE_CATCHALL</code>. It catches
485 exceptions of any type. If your program depends on it, then,
486 more often than not, there're something wrong with it.
487 </P>
488 </li>
490 <li><p>Instead of depending on <code>ACE_CATCHALL</code>, use
491 <code>std::unique_ptr</code> style mechanism to prevent memory leaks
492 from exceptions.
493 </p>
494 </li>
495 </ul>
497 <HR><P>
498 <h3><a name="general">General Guidelines for Exception Handling</h3>
499 <ul>
500 <li><p>Don't catch an exception just to rethrow it. Exceptions cost
501 you performance.
502 </p>
503 </li>
505 <li><p>When exceptions occur, make sure an object's is still in
506 a valid state or change to a state that can be safely
507 destructed.
508 </p>
509 </li>
511 <li><p>Watch out for side effect in the expression which may cause
512 exceptions. In the following example, what should
513 <code>i</code> be if an exception does occur?<br>
514 <pre>
515 ACE_TRY
517 obj[i++] = foo_bar_method (a, b ACE_ENV_ARG_PARAMETER);
519 </pre></p>
520 </li>
522 <li><p>Make sure an exception doesn't cause resource leak (memory,
523 socket, ...) (hint: Use std::unique_ptr to avoid memory leak,
524 and ACE_Guard for locks.)
525 </p>
526 </li>
528 <li><p>Don't catch any exception that you don't know how to handle.</p>
529 </li>
531 <li><p>Never throw an exception from destructor (unless you know what
532 it implies.)</p>
533 </li>
535 <li><p>Use exceptions to provide more information about the error.</p>
536 </li>
538 <li><p>Rethrow a different exception only to provide <em>more</em>
539 information. Do not catch an exception just to rethrow, say,
540 <code>unknow_exception</code>.</p>
541 </li>
542 </ul>
544 <HR><P>
545 <H3><a name="transition">Transition from ACE_TRY_ENV usage
546 to the ACE_ENV_ARG macros</h3>
548 <P>Before TAO version 1.2.2, IDL defined methods were declared using
549 direct mentions of <code>CORBA::Environment ACE_TRY_ENV</code>.
550 The problem with this approach was that the ACE_TRY_ENV had
551 to be passed into ORB core method calls even when native exceptions
552 are supported. The TAO internal usage of the ACE_ENV_ARG family of
553 macros fixes this.</p>
555 <p>For people who want to continue to use their old code that uses the
556 old <code>ACE_TRY_ENV</code> macros, they can define
557 <CODE>ACE_ENV_BKWD_COMPAT</CODE> in their <code>config.h</code> file.
559 <P>CORBA applications that do not need support for emulated exceptions
560 can use direct C++ exception handling and omit the CORBA::Environment
561 parameter entirely.<BR>
562 On the other hand, applications that shall support environments without
563 C++ exceptions (such as all applications that are part of to TAO itself)
564 should use the ACE_ENV_ARG macros.<BR>
565 The script <code>$ACE_ROOT/bin/subst_env.pl</code> can assist in the
566 conversion from the direct ACE_TRY_ENV usage to the ACE_ENV_ARG macros.
567 Here is a list of the substitutions that the script does. For context,
568 two sample IDL methods are used:
569 <PRE>
570 void noargs ();
571 void withargs (in boolean b);
572 </pre>
573 At each example, first the <em>old usage</em> is given, then its
574 <code>subsitution</code>.
575 </p>
577 <H4>Method declaration</h4>
579 <UL>
580 <li><P><em>void noargs (CORBA::Environment &amp;);</em></P>
581 <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL_NOT_USED);</code></P>
582 </li>
583 <li><P><em>void noargs (CORBA::Environment &amp;ACE_TRY_ENV);</em></P>
584 <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL);</code></P>
585 </li>
586 <li><P><em>void noargs (CORBA::Environment &amp;ACE_TRY_ENV = TAO_default_environment ());</em></P>
587 <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS);</code></P>
588 </li>
589 <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment &amp;);</em></P>
590 <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL_NOT_USED);</code></P>
591 </li>
592 <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment &amp;ACE_TRY_ENV);</em></P>
593 <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL);</code></P>
594 </li>
595 <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment &amp;
596 ACE_TRY_ENV = TAO_default_environment ());</em></P>
597 <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL_WITH_DEFAULTS);</code></P>
598 </li>
599 </ul>
601 <H4>Method invocation</h4>
603 <UL>
604 <li><P><em>noargs (ACE_TRY_ENV);</em></P>
605 <P><code>noargs (ACE_ENV_SINGLE_ARG_PARAMETER);</code></P>
606 </li>
607 <li><P><em>withargs (bparam, ACE_TRY_ENV);</em></P>
608 <P><code>withargs (bparam ACE_ENV_ARG_PARAMETER);</code></P>
609 </li>
610 </ul>
612 <HR><P>
613 <H3><a name="caveats">Caveats</H3>
615 <P>As we already mentioned no set of macros can cover all cases
616 and preserve the semantics between native C++ exceptions and the
617 <CODE>CORBA::Environment</CODE> based mapping.
618 Some of the problems that our macros are described below:
621 <UL>
622 <LI><P>Using the macros in loops can produce problems with
623 <CODE>break</CODE> and <CODE>continue</CODE> statements, for
624 example:
625 </P>
626 <PRE>
627 for (int i = 0; i < 10; ++i)
629 ACE_TRY
631 if (x[i] == 0)
632 continue; // will *not* work
633 if (x[i] == -1)
634 break; // will *not* work either
636 ACE_CATCH (CORBA::Exception, ex)
639 ACE_ENDTRY;
640 ACE_CHECK;
642 </PRE>
643 </LI>
644 </UL>
646 <P><HR><P>
648 Back to the <A
649 HREF="http://www.dre.vanderbilt.edu/~schmidt/ACE-documentation.html">ACE
650 documentation</A> page.<BR>
651 Back to <A HREF="index.html">ACE Documentation Home</A>.
654 <!--#include virtual="/~schmidt/cgi-sig.html" -->
655 </body></HTML>