ACE/docs/Symbol_Versioning.html

   1 <!--  -->
   2
   3 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   4 <html>
   5   <head>
   6     <title>Symbol Versioning in ACE</title>
   7   </head>
   8
   9   <body>
  10     <h3>Symbol Versioning in ACE</h3>
  11
  12     <p>
  13       To provide a means for ACE-based application developers to avoid
  14       symbol conflicts when multiple versions of ACE are linked to an
  15       application ACE supports <em>versioned namespaces</em>.  When
  16       enabled (disabled by default), ACE's versioned namespace support
  17       causes all ACE symbols (classes, free functions, etc) to be
  18       placed within a C++ namespace of the form "<code>namespace
  19         ACE_5_5_1</code>".  For example, the <code>ACE_Reactor</code>
  20       would end up being placed in the versioned namespace like so:
  21     </p>
  22
  23     <blockquote>
  24       <code>
  25 <pre>
  26         namespace ACE_5_5_1
  27         {
  28           class ACE_Reactor
  29           {
  30             ...
  31           };
  32         }
  33         using namespace ACE_5_5_1;
  34 </pre>
  35       </code>
  36     </blockquote>
  37
  38     <p>
  39       Notice that a <code>using</code> clause exposes the ACE types
  40       embedded in the versioned namespace back to the global
  41       namespace.  This maximizes source code compatibility.  ACE
  42       itself does this through the use of two macros:
  43     </p>
  44     <ul>
  45       <li>
  46         <code>ACE_BEGIN_VERSIONED_NAMESPACE_DECL</code><br>
  47         <ul>
  48           <li>
  49             Expands to "<code>namespace ACE_VERSIONED_NAMESPACE NAME
  50               {</code>", where
  51             <code>ACE_VERSIONED_NAMESPACE_NAME</code> by defaults to
  52             namespace name of the form
  53             <code>ACE_<em>major</em>_<em>minor</em>_<em>beta</em></code>.
  54             Users may override the default by defining the
  55             <code>ACE_VERSIONED_NAMESPACE_NAME</code> preprocessor
  56             symbol in their <code><strong>ace/config.h</strong></code>
  57             header file.
  58           </li>
  59         </ul>
  60       </li>
  61       <li>
  62         <code>ACE_END_VERSIONED_NAMESPACE_DECL</code>
  63         <ul>
  64           <li>
  65             Expands to "<code>} using namespace
  66               ACE_VERSIONED_NAMESPACE_NAME;</code>", where
  67             <code>ACE_VERSIONED_NAMESPACE_NAME</code> is described
  68             above.
  69           </li>
  70         </ul>
  71       </li>
  72     </ul>
  73     <h2>Things ACE-based Application Developers Should Know</h2>
  74     <p>
  75       Every effort has been made to make the versioned namespace
  76       support in ACE as transparent as possible, including transparent
  77       versioned symbol support in the ACE_Service_Configurator when
  78       the ACE_Service_Configurator macros, such as <em>e.g.</em>,
  79       <code>ACE_FACTORY_DECLARE</code>, are used appropriately.  No
  80       changes to service configurator directives are necessary.  For
  81       example, the <code>ACE_Service_Configurator</code> will
  82       transparently mangle the factory function name in a service
  83       configurator directive on-the-fly, meaning it will only load a
  84       "versioned" factory function name.  This allows multiple service
  85       object factory functions, for example, to coexist in the same
  86       process space.
  87     </p>
  88     <p>
  89       There is, however, at least one caveat with respect to source
  90       code compatibility: any forward declarations of ACE symbols must
  91       also be placed within the versioned namespace.  For example, if
  92       you have a forward declaration for <code>ACE_Reactor</code> in
  93       your application code, you will need to place it within the
  94       configured ACE versioned namespace as follows:
  95     </p>
  96     <blockquote>
  97       <code>
  98 <pre>
  99         ACE_BEGIN_VERSIONED_NAMESPACE_DECL
 100         class ACE_Reactor;
 101         ACE_END_VERSIONED_NAMESPACE_DECL
 102 </pre>
 103       </code>
 104     </blockquote>
 105     <p>
 106       This must only be done once, as these macros hide the versioned
 107       namespace name details from the application.  Alternatively, you
 108       could place the forward declaration in a namespace that is an
 109       alias of the ACE versioned namespace, <em>e.g.</em>:
 110     </p>
 111     <blockquote>
 112       <code>
 113 <pre>
 114         namespace Foo = ACE_VERSIONED_NAMESPACE_NAME;</code>
 115         namespace Foo {
 116           class ACE_Reactor;
 117         }
 118         using namespace Foo;
 119 </pre>
 120       </code>
 121     </blockquote>
 122     <p>
 123       Versioned namespace support in ACE may be enabled by adding
 124       <code>versioned_namespace=1</code> to your MPC
 125       <code><strong>default.features</strong></code> file.
 126     </p>
 127
 128     <h2>Things ACE Developers Should Know</h2>
 129     <p>
 130       ACE developers should place all ACE symbols that are potentially
 131       exposed to the user, including forward declarations in a
 132       versioned namespace using the
 133       <code>ACE_BEGIN_VERSIONED_NAMESSPACE_DECL</code> and
 134       <code>ACE_END_VERSIONED_NAMESPACE_DECL</code> macros.  Free
 135       functions that are declared to have a C calling convention
 136       (<em>i.e.</em>, <code>extern "C"</code>) should have their names
 137       mangled using the <code>ACE_PREPROC_CONCATENATE</code>
 138       preprocessor.  For example:
 139     </p>
 140     <blockquote>
 141       <code>
 142 <pre>
 143         void ACE_func (void) { ... }
 144         ...
 145         ACE_func(); // Call ACE_func()
 146 </pre>
 147       </code>
 148     </blockquote>
 149     <p>
 150       becomes:
 151     </p>
 152     <blockquote>
 153       <code>
 154 <pre>
 155         #if (defined (ACE_HAS_VERSIONED_NAMESPACE) \
 156              && ACE_HAS_VERSIONED_NAMESPACE == 1) \
 157           && !(defined (_MSC_VER) && _MSC_VER <= 1200)
 158         // MSVC++ 6's preprocessor can't handle macro expansions
 159         // required by the versioned namespace support.  *sigh*
 160
 161         # define ACE_FOO_FUNC_NAME ACE_PREPROC_CONCATENATE(ACE_VERSIONED_NAMESPACE_NAME, _ACE_foo_func)
 162
 163         #else
 164
 165         # define ACE_FOO_FUNC_NAME ACE_foo_func
 166
 167         #endif  /* ACE_HAS_VERSIONED_NAMESPACE == 1 */
 168
 169         ...
 170         void ACE_FOO_FUNC_NAME (void) { ... }
 171
 172         ACE_FOO_FUNC_NAME();  // Call mangled ACE_foo_func().
 173 </pre>
 174       </code>
 175     </blockquote>
 176     <p>
 177       The <code>ACE_PREPROC_CONCATENATE</code> is used rather than a
 178       straight <code>##</code> preprocessor concatenation since in the
 179       latter case preprocessor symbols like
 180       <code>ACE_VERSIONED_NAMESPACE_NAME</code> will not be expanded
 181       if they are concatenated.  <code>ACE_PREPROC_CONCATENATE</code>
 182       forces the preprocessor to expand them during the argument
 183       prescan by calling a macro that itself calls another that
 184       performs the actual concatenation.
 185     </p>
 186     <h3>General Guidelines</h3>
 187     <ul>
 188       <li>
 189         Versioned namespace macro/support must be added to all new files
 190         added to ACE.
 191       </li>
 192       <li>
 193         Do not place include directives between
 194         <code>ACE_BEGIN_VERSIONED_NAMESPACE_DECL</code> and
 195         <code>ACE_END_VERSIONED_NAMESPACE_DECL</code> macros.  Doing
 196         so  will cause nested namespace to be created, which is not
 197         the desired affect.
 198       </li>
 199       <li>Be aware of preprocessor conditional blocks when placing the
 200         versioned namespace macros.  For example, if you open
 201         versioned namespace within a given preprocessor condition
 202         block, you'll most likely want to close it in the same
 203         block.
 204       </li>
 205       <li>
 206         If necessary, reopen and close the versioned namespace
 207         multiple times in the same file by using the macros multiple
 208         times to address the concerns described in the above two
 209         items.
 210       </li>
 211       <li>
 212         The <code>$ACE_ROOT/bin/fuzz.pl</code> script has a sanity
 213         checking test for versioned namespaces that may be of use when
 214         debugging nested namespace issues, and for detecting
 215         <code>BEGIN</code>/<code>END</code> mismatches.
 216       </li>
 217     </ul>
 218     <p>
 219       Versioned namespace support in ACE may be enabled by adding
 220       <code>versioned_namespace=1</code> to your MPC
 221       <code><strong>default.features</strong></code> file.  Additional
 222 information about versioned namespaces is available from the <A
 223 HREF="http://www.riverace.com/newsletters/March2006.htm">Riverace
 224 website</A>.
 225     </p>
 226     <hr>
 227     <address><a href="mailto:ossama@dre.vanderbilt.edu">Ossama Othman</a></address>
 228 <!-- Created: Fri Mar 17 08:35:50 PST 2006 -->
 229 <!-- hhmts start -->
 230 Last modified:
 231 <!-- hhmts end -->
 232   </body>
 233 </html>