CORBA Environment
arguments provide a way to handle exceptions
when native c++ exception handling is unavailable or undesirable. However,
writing portable code using both native C++ exception handling and
CORBA::Environment
objects is very hard. If you plan to write
portable code that must run on platforms that do not have native C++ exceptions,
therefore, we recommend you use the ACE exception macros. This document explains
how these macros can help alleviate much of the accidental complexity. However,
keep in mind macros cannot solve all problems perfectly.
Before reading the rest of this document, we recommend you check out pages 307 through to 322 in the book, Advanced Corba Programming with C++ by Michi Henning & Steve Vinoski. Likewise, we recommend that you read the Error Handling chapter from the TAO Developer's Guide.
This section explains some simple rules of writing programs for platforms with and without native exception support using ACE's exception macros.
ACE exception macros are modelled like C++ language exceptions and can be used like them, but with a small difference. These macros rely on the CORBA::Environment variable to handle exceptions on platforms that do not support exception handling. (Please note that native exceptions can be turned on or off at COMPILE time as an option to your make) The exception macros have been modelled with some extra rules to ensure this works even on platforms without native exception support. See some quick examples on how to use ACE exception macros.
Declaration of CORBA::Environment Parameter at Methods
On
platforms lacking native exceptions, all CORBA methods take an extra parameter
added at the end of their argument list. This last parameter holds the
CORBA::Environment variable. However, on systems with native exceptions, no
such extra method parameter is added.
In order for both configurations to
work with the same source code, following macros are defined. In native
exception configurations, they all resolve to empty.
ACE_ENV_ARG_DECL
in the pseudo exception configuration resolves to, CORBA::Environment ACE_TRY_ENVIt is used for declaring the extra Environment parameter at CORBA methods that take one or more regular parameters. The fact that the comma is part of the macro substitution caters for the hiding of this added argument when native exceptions are used. However, by the same virtue its usage is a bit peculiar -
void mymethod (in boolean b);may be declared as follows in C++:
void mymethod (CORBA::Boolean b ACE_ENV_ARG_DECL);Notice the missing comma before the ACE_ENV_ARG_DECL. This notation is necessary because when using native exceptions, also the presence of the comma before the (non-existent) CORBA::Environment parameter must be hidden.
ACE_ENV_SINGLE_ARG_DECL
is similar toACE_ENV_ARG_DECL
, but is used when the method takes no other
parameters. It is necessary as a separate macro because it does not contain
the leading comma that ACE_ENV_ARG_DECL
does. Example: a CORBA
IDL defined method void mymethod ();may look like this in C++:
void mymethod (ACE_ENV_SINGLE_ARG_DECL);
ACE_ENV_ARG_DECL_WITH_DEFAULTS,
TAO_default_environment()
.
Notice that these macros are only used at the declaration of methods (usually in header files), not at their definition (usually in implementation files.) At the definition, instead use the corresponding macro without "_WITH_DEFAULTS". Example: the CORBA IDL defined method
void mymethod ();in the C++ header file looks like this:
void mymethod (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS);and in the C++ implementation file may look something like:
void mymethod (ACE_ENV_SINGLE_ARG_DECL) { // ... }
Passing the CORBA::Environment Parameter into Method Calls
Now
that we've seen how to declare methods with Environment parameters, let's see
how to invoke such methods.
ACE_ENV_ARG_PARAMETER
in the pseudo exception configuration resolves to, ACE_TRY_ENVand is written as the last parameter of a method call that takes one or more regular parameters. Again we need to omit the comma that would normally precede this last parameter, as the comma is already part of the macro definition. For example, the CORBA IDL method
void mymethod (in boolean b);would be invoked as follows:
some_var.mymethod (bparam ACE_ENV_ARG_PARAMETER);
ACE_ENV_SINGLE_ARG_PARAMETER
is similar toACE_ENV_ARG_PARAMETER
but is used for calling methods that
don't take any regular parameters. Our example of a CORBA IDL method void mymethod ();we would invoke as follows:
some_var.mymethod (ACE_ENV_SINGLE_ARG_PARAMETER);
Definition of the CORBA::Environment variable
We have seen how
to declare methods with the CORBA::Environment parameter, and how to invoke
such methods. However, where does the variable to pass into methods as the
CORBA::Environment parameter come from in the first place?
An environment variable can be defined in the needed scope (for example, in the main program, or in a more local scope) by the statement
ACE_DECLARE_NEW_CORBA_ENV;
You can then invoke the methods on the servant from the client side as
object_reference->func_name (x, y ACE_ENV_ARG_PARAMETER);Even if you are interested in making calls within the client side, you can define your method like this
int AN_OBJ::foobar (int a, int b ACE_ENV_ARG_DECL);
Throwing exceptions:
Use ACE_THROW
and
ACE_THROW_RETURN
to throw exceptions. They should never be used
within a try block; please use ACE_TRY_THROW
instead.
Propagating exceptions:
To simulate native exceptions on
platforms without native exception handling, every function call that
may throw exceptions must be followed by ACE_CHECK
or
ACE_CHECK_RETURN
.
Exception-throwing functions include the following categories:
Any function that takes a CORBA_Environment
argument.
ACE_NEW_THROW_EX
. Notice that you should not use
ACE_NEW_THROW
, ACE_NEW_THROW_RETURN
,
ACE_NEW_TRY_THROW
anymore because they don't work right with
ACE try macros. Instead, use ACE_NEW_THROW
with appropriate
ACE_CHECK* macros.
ACE_GUARD_THROW_EX
, ACE_READ_GURAD_THROW_EX
,
and ACE_WRITE_THROW_EX
.
ACE_TRY
blocks. Follow every ACE_ENDTRY
with
appropriate ACE_CHECK* macros.
You should pass ACE_TRY_ENV
to these functions.
Be very careful not to combine exception throwing functions in one statement like this:
x = obj1->callme (ACE_ENV_SINGLE_ARG_PARAMETER) + obj2->dare_me (ACE_ENV_SINGLE_ARG_PARAMETER); ACE_CHECK;
This example may work differently when native exception handling is enabled/disabled.
Catching exceptions:
Use ACE_TRY
to catch
exceptions if there's an ACE_TRY_ENV
available. Otherwise, you
should use ACE_DECLARE_NEW_CORBA_ENV
to create one at
proper scope. The use of ACE_TRY_NEW_ENV
is considered
depricated because it can't deal with the case when you have multiple
TRY
blocks in the scope of ACE_TRY_NEW_ENV
. If there
are more than one try blocks in a function, use ACE_TRY_EX
for
all subsequence try blocks to avoid name clashing of labels.
Within a ACE_TRY
block, use the variable
ACE_TRY_ENV
to pass down the CORBA_Environment
(see this
example.)
Follow every exception throwing function with
ACE_TRY_CHECK
. If you are using a TRY block within another try
block add a ACE_TRY_CHECK
at the end of this TRY block ie.
after ACE_ENDTRY
.
Use ACE_CATCH
to catch exceptions of certain type.
ACE_CATCHANY
catches any exceptions of type
CORBA_Exception
. The caught exception is stored in a variable
call ACE_ANY_EXCEPTION
.
ACE_CATCHALL
emulate the catch (...)
c++
statement. It is identical to ACE_CATCHANY
on platforms without
native exception support. You can not access the caught exception within the
ACE_CATCHALL
block.
Use ACE_RE_THROW
to rethrow the same exception within a
ACE_CATCH
or ACE_CATCHANY
block.
A ACE_TRY
block must be terminated with a
ACE_ENDTRY
statement.
Throw an exception within a ACE_TRY
block or
ACE_CATCH
block using ACE_TRY_THROW
.
Printing out exceptions. Use ACE_PRINT_EXCEPTION
(EX,INFO)
to print out an exception. The macro takes two arguments, a
reference to an exception (EX) and a char *
string (INFO) which
provides more information on the exception. Since there's no portable way to
print out exceptions, you can redefine ACE_PRINT_EXCEPTION to fit your need
(or define it to null.) You should always print out the exception itself,
not the CORBA_Environment that carries the exception.
Name of CORBA::Environment variable
A function that may throw a
CORBA::Exception needs a CORBA::Environment variable to pass up exceptions (to
throw in the C++ sense) and to gather (catch () in the C++ sense) exceptions
from functions it called. By default, ACE exception macros assume that the
variable is named ACE_TRY_ENV
. ACE_TRY_ENV
itself is
also a macro which can be redefined.
You can redefine the name of the variable to something else to avoid name
clashing. Alternatively, there's another macro
(ACE_ADOPT_CORBA_ENV
) that allow you to use another variable name
as the default CORBA::Environment within a function.
$ACE_ROOT/ace/CORBA_macros.h
for complete definitions of macros discussed here.
ACE_TRY // Use ACE_DECLARE_NEW_CORBA_ENV to create ACE_TRY_ENV // if you got undefined symbol warning here. { some_operation (arg1, arg2 ACE_ENV_ARG_PARAMETER); ACE_TRY_CHECK; . . if (whatever) ACE_TRY_THROW (CORBA::BAD_PARAM ()); some_other_operation (arg1, arg2, arg3 ACE_ENV_ARG_PARAMETER); 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_RE_THROW; } ACE_ENDTRY; ACE_CHECK;
ACE_TRY
and also declares a label for internal use. To avoid
defining the same label multiple times within a function, use
ACE_TRY_EX
with different labels for different try blocks
instead. For example,
ACE_TRY_EX (block_1) { some_operation (arg1, arg2 ACE_ENV_ARG_PARAMETER); ACE_TRY_CHECK_EX (block_1); some_other_operation (arg1, arg2, arg3 ACE_ENV_ARG_PARAMETER); 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_ENV_ARG_PARAMETER); ACE_TRY_CHECK_EX (block_2); bar (arg1, arg2 ACE_ENV_ARG_PARAMETER); ACE_TRY_CHECK_EX (block_2); } ACE_CATCH (CORBA_some_exception, ex) { // error handling. } ACE_CATCHANY { // error handling. } ACE_ENDTRY; ACE_CHECK_RETURN (-1);
You may want to make a different series of calls after you encounter/catch an exception. Here is what we recommend.
ACE_TRY { // Calls that can raise an exception some_call1 (arg1, arg2 ACE_ENV_ARG_PARAMETER); ACE_TRY_CHECK; . . . ACE_TRY_CHECK; } ACE_CATCH (CORBA_some_exception, ex) { // Caught an exception, so we need to make some other calls // to continue.. ACE_TRY_EX (block1) // basically a label { some_other_call1 (arg1,.. ACE_ENV_ARG_PARAMETER); ACE_TRY_CHECK_EX (block1); } ACE_CATCH (CORBA_some_other_exception, ex1) { // Handle the exception here.. } ACE_ENDTRY; ACE_CHECK_RETURN (-1); // Needed to catch uncaught exceptions } ACE_ENDTRY; ACE_CHECK_RETURN (-1);
Be VERY wary of ACE_CATCHALL
. It catches exceptions
of any type. If your program depends on it, then, more often than not,
there're something wrong with it.
Instead of depending on ACE_CATCHALL
, use
auto_ptr
style mechanism to prevent memory leaks from exceptions.
Don't catch an exception just to rethrow it. Exceptions cost you performance.
When exceptions occur, make sure an object's is still in a valid state or change to a state that can be safely destructed.
Watch out for side effect in the expression which may cause exceptions. In
the following example, what should i
be if an exception does
occur?
ACE_TRY { obj[i++] = foo_bar_method (a, b ACE_ENV_ARG_PARAMETER); }
Make sure an exception doesn't cause resource leak (memory, socket, ...) (hint: Use auto_ptr to avoid memory leak, and ACE_Guard for locks.)
Don't catch any exception that you don't know how to handle.
Never throw an exception from destructor (unless you know what it implies.)
Use exceptions to provide more information about the error.
Rethrow a different exception only to provide more information. Do
not catch an exception just to rethrow, say,
unknow_exception
.
Before TAO version 1.2.2, IDL defined methods were declared using direct
mentions of CORBA::Environment ACE_TRY_ENV
. The problem with this
approach was that the ACE_TRY_ENV had to be passed into ORB core method calls
even when native exceptions are supported. The TAO internal usage of the
ACE_ENV_ARG family of macros fixes this.
For people who want to continue to use their old code that uses the old
ACE_TRY_ENV
macros, they can define
ACE_ENV_BKWD_COMPAT
in their config.h
file.
CORBA applications that do not need support for emulated exceptions can use
direct C++ exception handling and omit the CORBA::Environment parameter
entirely.
On the other hand, applications that shall support environments
without C++ exceptions (such as all applications that are part of to TAO itself)
should use the ACE_ENV_ARG macros.
The script
$ACE_ROOT/bin/subst_env.pl
can assist in the conversion from the
direct ACE_TRY_ENV usage to the ACE_ENV_ARG macros. Here is a list of the
substitutions that the script does. For context, two sample IDL methods are
used:
void noargs (); void withargs (in boolean b);At each example, first the old usage is given, then its
subsitution
.
void noargs (CORBA::Environment &);
void noargs (ACE_ENV_SINGLE_ARG_DECL_NOT_USED);
void noargs (CORBA::Environment &ACE_TRY_ENV);
void noargs (ACE_ENV_SINGLE_ARG_DECL);
void noargs (CORBA::Environment &ACE_TRY_ENV = TAO_default_environment ());
void noargs (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS);
void withargs (CORBA::Boolean b, CORBA::Environment &);
void withargs (CORBA::Boolean b
ACE_ENV_ARG_DECL_NOT_USED);
void withargs (CORBA::Boolean b, CORBA::Environment &ACE_TRY_ENV);
void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL);
void withargs (CORBA::Boolean b, CORBA::Environment & ACE_TRY_ENV = TAO_default_environment ());
void withargs (CORBA::Boolean b
ACE_ENV_ARG_DECL_WITH_DEFAULTS);
noargs (ACE_TRY_ENV);
noargs (ACE_ENV_SINGLE_ARG_PARAMETER);
withargs (bparam, ACE_TRY_ENV);
withargs (bparam ACE_ENV_ARG_PARAMETER);
As we already mentioned no set of macros can cover all cases and preserve the
semantics between native C++ exceptions and the CORBA::Environment
based mapping. Some of the problems that our macros are described below:
Using the macros in loops can produce problems with break
and
continue
statements, for example:
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; ACE_CHECK; }