TAO/docs/LocalObject.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <!--  -->
   3 <html> <head>
   4 <title>Implementing and Using Local Objects</title>
   5 </head>
   6
   7 <body text="#000000" bgcolor="#FFFFFF">
   8 <h1>Implementing Local Objects</h1>
   9
  10 <p>The new addition of "<code>local</code>" interfaces in CCM define a
  11 standard behavior of locality constraint object.  There are some
  12 subtle differences in implementing and using local interfaces compared
  13 to regular (remote) interfaces.  This page tries to collect
  14 information on things to notice and common pitfalls.</p>
  15
  16 <ul>
  17   <li><p><b>Local or not Local?</b> - A local interface is local.
  18       Any types defined withing the interface are also local.  They
  19       include "struct, union, enum, sequence, exceptions, typedef..."
  20       For constructed types, if a constructed type contains local
  21       elements, then it also becomes local even if the type is not
  22       defined within a local interface.</p>
  23
  24   <li><p>You can not put objects of local types into Any's or try to use
  25       it regular CORBA invocations.</p>
  26
  27   <li><p><b>Implementation class</b> - Instead of inheriting from
  28       <code>POA_FOOBAR</code> class, the implementation of local
  29       interface inherit from both the C++ object mapping class (the
  30       client side class) and the <code>CORBA::LocalObject</code>.  For
  31       example, when <code>FOOBAR</code> is a regular interface, the
  32       declaration of the implementation class is something like this:
  33 <pre>
  34
  35         class FOOBAR_i : public virtual POA_FOOBAR
  36         {
  37           .  .  .
  38         };
  39
  40 </pre>
  41       However, if <code>FOOBAR</code> is defined as a local interface,
  42       the implementation class is defined as:
  43 <pre>
  44
  45         class FOOBAR_i : public virtual FOOBAR,
  46                          public virtual CORBA::LocalObject
  47         {
  48           .  .  .
  49         };
  50
  51 </pre></p>
  52
  53   <li><p><b>Reference Counting and Object Reference Lifecycle
  54       (TAO 1.6.5 and above, which followed the IDL->C++ mapping version 1.2)</b> -
  55       TAO 1.6.5 and above has been updated to the 1.2 IDL to C++ mapping.
  56       LocalObject is now refcounted by default. Regular CORBA object
  57       references use reference counting to manage lifecycle of object
  58       references. Local object references also use reference counting
  59       for lifecycle management. In that respect, Local Objects behave
  60       exactly as Regular CORBA objects do, and the memory management
  61       rules that apply to Regular CORBA objects apply to Local Objects
  62       </p>
  63
  64       <p>If, for some reason, you would like to preserve the originial
  65       behavior (i.e., disabling reference counting) then override
  66       <code>_add_ref ()</code> and <code>_remove_ref
  67       ()</code> and implement them as no-op operations.</p>
  68
  69
  70   <li><p><b>Reference Counting and Object Reference Lifecycle (Prior to
  71             TAO 1.6.5, which followed the IDL->C++ mapping version 1.1)</b> -
  72       Regular CORBA object references use reference counting to manage
  73       lifecycle of object references.  Local object references
  74       <b>may</b> also use reference counting for lifecycle
  75       management.</p>
  76
  77       <p>There are <code>_add_ref ()</code> and <code>_remove_ref
  78       ()</code> operations defined in all local object and the ORB
  79       uses these operations to increase/decrease the reference count
  80       when <code>_duplicate ()</code> or <code>CORBA::release
  81       ()</code> are invoked on an ojbect reference.  <b>However,
  82       notice that the default implementation of <code>_add_ref
  83       ()</code> and <code>_remove_ref ()</code> for local objects are
  84       no-ops.</b>  Therefore, if you wish to do reference counting on
  85       your local object instances, you must overwrite <code>_add_ref
  86       ()</code> and <code>_remove_ref ()</code> in your implementation
  87       for that local object.</p>
  88
  89       <p>By leaving <code>_add_ref ()</code> and <code>_remove_ref
  90       ()</code> as no-ops, you assume the responsibility of managing
  91       the local object instance.  Objects that have the same lifetime
  92       as the ORB may want to use this strategy and let the ORB to
  93       manage these instances of local objects.  This prevents user
  94       errors from crashing the server process.  However, in this case,
  95       the object needs to be <code>delete</code>'d explicitly (as
  96       <code>CORBA::release ()</code> basically doesn't do anything in
  97       this case.</p>
  98
  99       <p>TAO developers can get reference counting by using the mixin class
 100       <code>TAO_Local_Ref_Counted_Object ()</code> as:
 101
 102       <pre>
 103        class FOOBAR_i : public virtual FOOBAR,
 104                         public virtual TAO_Local_Ref_Counted_Object
 105        {
 106           .  .  .
 107        };
 108        </pre>
 109
 110       if you wish to use reference counting.  However,
 111       this is not portable and should be used with care by the applications.</p>
 112
 113 </ul>
 114
 115
 116 <hr>
 117 <address></address>
 118 <!-- hhmts start -->
 119 Last modified: Tue Jun  3 15:19:18 UTC 2008
 120 <!-- hhmts end -->
 121 </body> </html>