diff options
| -rw-r--r-- | ACE-INSTALL.html | 14 | ||||
| -rw-r--r-- | ChangeLog | 8 | ||||
| -rw-r--r-- | ChangeLogs/ChangeLog-02a | 8 | ||||
| -rw-r--r-- | ChangeLogs/ChangeLog-03a | 8 | ||||
| -rw-r--r-- | docs/exceptions.html | 116 |
5 files changed, 93 insertions, 61 deletions
diff --git a/ACE-INSTALL.html b/ACE-INSTALL.html index dfa7f447f7e..5bb5f8f3e09 100644 --- a/ACE-INSTALL.html +++ b/ACE-INSTALL.html @@ -2712,6 +2712,20 @@ Flag Description ---- ----------- debug Enable debugging; see DCFLAGS and DCCFLAGS. exceptions Enable exception handling (not supported by all platforms). +include_env Support old-style ACE_TRY_ENV declarations in methods. + This switch is necessary for compiling TAO applications + in the native exception configuration that were written + for TAO versions before 1.2.2. + In TAO 1.2.2, new macros were introduced that supercede + the direct ACE_TRY_ENV declarations. These are the + ACE_ENV_ARG macros that are defined in ace/CORBA_macros.h + and are documented in docs/exceptions.html. + This switch only affects the exceptions=1 configuration. + It is for backward compatibility only. + There will be warnings about unused _ACE_environment_variable + parameters when using include_env=1. + If possible, do not use it, but instead change your TAO + applications to use the ACE_ENV_ARG macros. fast Enable -fast option, e.g., with Sun C++. inline Enable ACE inlining. Some platforms enable inlining by default, others do not. diff --git a/ChangeLog b/ChangeLog index bc36efefa40..0a6730262c8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +Thu Feb 7 08:16:24 2002 Oliver Kellogg <oliver.kellogg@sysde.eads.net> + + * ACE-INSTALL.html: Document the include_env=1 make switch. + + * docs/exceptions.html: Replaced the "Transition from TAO_TRY + to ACE_TRY" section with "Transition from ACE_TRY_ENV usage + to ACE_ENV_ARG". + Wed Feb 6 06:57:35 2002 Balachandran Natarajan <bala@cs.wustl.edu> * tests/run_test.lst: Disabled TP_Reactor_Test as the test is diff --git a/ChangeLogs/ChangeLog-02a b/ChangeLogs/ChangeLog-02a index bc36efefa40..0a6730262c8 100644 --- a/ChangeLogs/ChangeLog-02a +++ b/ChangeLogs/ChangeLog-02a @@ -1,3 +1,11 @@ +Thu Feb 7 08:16:24 2002 Oliver Kellogg <oliver.kellogg@sysde.eads.net> + + * ACE-INSTALL.html: Document the include_env=1 make switch. + + * docs/exceptions.html: Replaced the "Transition from TAO_TRY + to ACE_TRY" section with "Transition from ACE_TRY_ENV usage + to ACE_ENV_ARG". + Wed Feb 6 06:57:35 2002 Balachandran Natarajan <bala@cs.wustl.edu> * tests/run_test.lst: Disabled TP_Reactor_Test as the test is diff --git a/ChangeLogs/ChangeLog-03a b/ChangeLogs/ChangeLog-03a index bc36efefa40..0a6730262c8 100644 --- a/ChangeLogs/ChangeLog-03a +++ b/ChangeLogs/ChangeLog-03a @@ -1,3 +1,11 @@ +Thu Feb 7 08:16:24 2002 Oliver Kellogg <oliver.kellogg@sysde.eads.net> + + * ACE-INSTALL.html: Document the include_env=1 make switch. + + * docs/exceptions.html: Replaced the "Transition from TAO_TRY + to ACE_TRY" section with "Transition from ACE_TRY_ENV usage + to ACE_ENV_ARG". + Wed Feb 6 06:57:35 2002 Balachandran Natarajan <bala@cs.wustl.edu> * tests/run_test.lst: Disabled TP_Reactor_Test as the test is diff --git a/docs/exceptions.html b/docs/exceptions.html index 5b8d2e13cab..ff95176ace3 100644 --- a/docs/exceptions.html +++ b/docs/exceptions.html @@ -33,8 +33,8 @@ Vinoski</A>. Likewise, we recommend that you read the Error Handling chapter fr <li><a href="#nutshell">ACE Try Macros in a Nutshell</a> <li><a href="#examples">Examples</a> <li><a href="#general">General Guidelines for Exception Handling</a> - <li><a href="#transition">Transition from TAO try macros to ACE try - macros</a> + <li><a href="#transition">Transition from ACE_TRY_ENV usage to the + ACE_ENV_ARG macros</a> <li><a href="#caveats">Some Caveats</a> </ul> @@ -81,7 +81,7 @@ macros. usage is a bit peculiar -<br> Example: a CORBA IDL defined method <pre> - void mymethod (boolean b); + void mymethod (in boolean b); </pre> may be declared as follows in C++: <pre> @@ -149,7 +149,7 @@ macros. comma is already part of the macro definition. For example, the CORBA IDL method <pre> - void mymethod (boolean b); + void mymethod (in boolean b); </pre> would be invoked as follows: <pre> @@ -542,74 +542,68 @@ macros discussed here. </ul> <HR><P> -<H3><a name="transition">Transition from TAO try macros to ACE try macros</h3> +<H3><a name="transition">Transition from ACE_TRY_ENV usage + to the ACE_ENV_ARG macros</h3> + +<P>Before TAO version 1.2.2, IDL defined methods were declared using +direct mentions of <code>CORBA::Environment ACE_TRY_ENV</code>. +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.</p> + +<P>CORBA applications that do not need support for emulated exceptions +can use direct C++ exception handling and omit the CORBA::Environment +parameter entirely.<BR> +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.<BR> +The script <code>$ACE_ROOT/bin/subst_env.pl</code> 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: +<PRE> + void noargs (); + void withargs (in boolean b); +</pre> +At each example, first the <em>old usage</em> is given, then its +<code>subsitution</code>. +</p> + +<H4>Method declaration</h4> -This list tries to give a comprehensive list of mapping between TAO -try macros and ACE try macros. It's sole purpose is to provide hints -in the converting the use of TAO try macros to ACE try macros and is -by no mean complete. - -<OL> - <li><P>Rename all <code>CORBA_Environment</code> variables to - <code>ACE_TRY_ENV</code>. </P> - </li> - - <li><P>Replace <code>TAO_TRY</code> <code>TAO_TRY_VAR</code> with - <code>ACE_TRY</code>. Added - <code>ACE_DECLARE_NEW_CORBA_ENV</code> if necessary.</p> +<UL> + <li><P><em>void noargs (CORBA::Environment &);</em></P> + <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL_NOT_USED);</code></P> </li> - - <li><p>Replace <code>TAO_TRY_EX</code> <code>TAO_TRY_VAR_EX</code> - with <code>ACE_TRY_EX</code>.</p> + <li><P><em>void noargs (CORBA::Environment &ACE_TRY_ENV);</em></P> + <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL);</code></P> </li> - - <li><p>Replace <code>TAO_CHECK_RETURN</code> and - <code>TAO_CHECK_RETURN_VOID</code> with <code>ACE_CHECK_RETURN</code> - and <code>ACE_CHECK</code>. These macros are used - <em>outside</em> of TRY/CATCH blocks.</P> + <li><P><em>void noargs (CORBA::Environment &ACE_TRY_ENV = TAO_default_environment ());</em></P> + <P><code>void noargs (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS);</code></P> </li> - - <li><P>Replace <code>TAO_THROW</code>, <code>TAO_THROW_ENV</code>, - <code>TAO_THROW_RETURN</code>, <code>TAO_THROW_ENV_RETURN</code> - with <code>ACE_THROW</code> and - <code>ACE_THROW_RETURN</code>. </p> + <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment &);</em></P> + <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL_NOT_USED);</code></P> </li> - - <li><P>Replace <code>ACE_NEW_THROW</code>, - <code>ACE_NEW_THROW_RETURN</code>, - <code>ACE_TRY_NEW_THROW</code> with - <code>ACE_NEW_THROW_EX</code> and appropriate - <code>ACE_CHECK*</code> macros. aformention</P> - - <li><p>Replace <code>TAO_CHECK_ENV</code> and - <code>TAO_CHECK_ENV_EX</code> with <code>ACE_TRY_CHECK</code> - and <code>ACE_TRY_CHECK_EX</code>.</p> + <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment &ACE_TRY_ENV);</em></P> + <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL);</code></P> </li> - - <li><p>Replace <code>TAO_TRY_THOW</code> and - <code>TAO_TRY_THROW_EX</code> with <code>ACE_TRY_THROW</code> - and <code>ACE_TRY_THROW_EX</code>. Notice that you can also use - <code>ACE_TRY_THROW*</code> within CATCH blocks.</p> + <li><P><em>void withargs (CORBA::Boolean b, CORBA::Environment & + ACE_TRY_ENV = TAO_default_environment ());</em></P> + <P><code>void withargs (CORBA::Boolean b ACE_ENV_ARG_DECL_WITH_DEFAULTS);</code></P> </li> +</ul> - <li><p>Replace <code>TAO_RETHROW</code>, - <code>TAO_RETHROW_RETURN</code>, - <code>TAO_RETHROW_RETURN_VOID</code> with - <code>ACE_RETHROW</code>.</p> - </li> +<H4>Method invocation</h4> - <li><p>Replace <code>TAO_CATCH</code>, <code>TAO_CATCHANY</code>, - and <code>TAO_CATCHALL</code> with <code>ACE_CATCH</code>, - <code>ACE_CATCHANY</code> and <code>ACE_CATCHALL</code> - respectively. </p> +<UL> + <li><P><em>noargs (ACE_TRY_ENV);</em></P> + <P><code>noargs (ACE_ENV_SINGLE_ARG_PARAMETER);</code></P> </li> - - <li><p>Replace <code>TAO_ENDTRY</code> with <code>ACE_ENDTRY</code> - followed by an appropriate CHECK macro (<code>ACE_CHECK</code>, - <code>ACE_CHECK_RETURN</code>, <code>ACE_TRY_CHECK</code>, or - <code>ACE_TRY_CHECK_EX</code>.)</P> + <li><P><em>withargs (bparam, ACE_TRY_ENV);</em></P> + <P><code>withargs (bparam ACE_ENV_ARG_PARAMETER);</code></P> </li> -</ol> +</ul> <HR><P> <H3><a name="caveats">Caveats</H3> |