TAO/tao/Intrusive_Ref_Count_Handle_T.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Intrusive_Ref_Count_Handle_T.h
   6  *
   7  *  @authors Tim Bradley  <bradley_t@ociweb.com>
   8  */
   9 //=============================================================================
  10
  11 #ifndef TAO_INTRUSIVE_REF_COUNT_HANDLE_T_H
  12 #define TAO_INTRUSIVE_REF_COUNT_HANDLE_T_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include "ace/config-all.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include /**/ "tao/Versioned_Namespace.h"
  23
  24 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 /**
  27  * @class TAO_Intrusive_Ref_Count_Handle<T>
  28  *
  29  * @brief Template class for smart-pointer to (intrusively) ref-counted object.
  30  *
  31  *  This class behaves just like a xxx_var type behaves.  The only significant
  32  *  difference is that this class provides a "bool is_nil() const" method,
  33  *  and xxx_var types don't (they use the "bool CORBA::is_nil(xxx_ptr ptr)"
  34  *  method instead). For example,
  35  *
  36  *  typedef TAO_Intrusive_Ref_Count_Handle<PortableServer::ServantBase>
  37  *      MyServantBase_var;
  38  *
  39  *  The MyServantBase_var and the PortableServer::ServantBase_var are
  40  *  nearly idenitical.  The only difference is that the MyServantBase_var
  41  *  has a "isNil()" method that indicates whether or not the smart pointer
  42  *  is in the 'nil' state or not.
  43  *
  44  *  This class can be used to "safely" deal with an instance of a servant.
  45  *  For example, we can use a single variable
  46  *  TAO_Intrusive_Ref_Count_Handle<Foo_i>
  47  *
  48  *      typedef TAO_Intrusive_Ref_Count_Handle<Foo_i> Foo_i_var;
  49  *      Foo_i_var servant_;
  50  *
  51  *  instead of using two variables
  52  *
  53  *      PortableServer::ServantBase_var servant_holder_;
  54  *      Foo_i* servant_;
  55
  56  *  to deal with the servant memory.
  57  *
  58  *  The Foo_i_var type does everything that the PortableServer::ServantBase_var
  59  *  type does. In addition, the Foo_i_var type can provide access to the servant
  60  *  as derived class via the arrow operator.
  61  */
  62 template <typename T>
  63 class TAO_Intrusive_Ref_Count_Handle
  64 {
  65 public:
  66   /// Default Constructor - enters the "nil" state.
  67   TAO_Intrusive_Ref_Count_Handle ();
  68
  69   /// Ctor - By default, takes ownership of passed-in "copy" of reference
  70   ///        to T.  But the second argument (bool) can be changed from
  71   ///        the default value of 'true' to the non-default value of 'false'.
  72   ///        The second argument dictates whether or not this handle object
  73   ///        should take ownership of the passed-in pointer to the T object.
  74   ///        By default, it takes ownership, leaving the reference counter
  75   ///        of the T object unchanged.  When it is instructed to not take
  76   ///        ownership (false value for second arg), then the reference
  77   ///        counter of the T object will be incremented so that this
  78   ///        handle object has its own "copy".
  79   TAO_Intrusive_Ref_Count_Handle (T* p, bool take_ownership = true);
  80
  81   /// Copy Constructor - claims a "copy" of rhs object's reference to T.
  82   TAO_Intrusive_Ref_Count_Handle (const TAO_Intrusive_Ref_Count_Handle& b);
  83
  84   /// Destructor
  85   ~TAO_Intrusive_Ref_Count_Handle ();
  86
  87   /// Assignment Operator with T* argument.
  88   /// Takes ownership of passed-in "copy" of reference to T.
  89   TAO_Intrusive_Ref_Count_Handle& operator= (T* p);
  90
  91   /// Assignment Operator with const TAO_Smart_Ptr<T>& argument.
  92   /// Claims a "copy" of rhs object's reference to T.
  93   TAO_Intrusive_Ref_Count_Handle& operator=
  94                                    (const TAO_Intrusive_Ref_Count_Handle& b);
  95
  96   /// Const Accessor to underlying pointer (T*) using arrow (->) operator.
  97   T* operator->() const;
  98
  99   /// Returns true if underlying pointer is NULL (0).
 100   /// Returns false otherwise.
 101   bool is_nil () const;
 102
 103   /// Used to pass the underlying pointer as an "IN" argument to a method.
 104   T* in () const;
 105
 106   /// Used to pass the underlying pointer as an "IN/OUT" argument to a method.
 107   T*& inout ();
 108
 109   /// Used to pass the underlying pointer as an "OUT" argument to a method.
 110   T*& out ();
 111
 112   /// Used to take-away the underlying pointer from this smart pointer object.
 113   /// Caller becomes responsibe for the returned "copy" to the reference.
 114   /// Always leaves the smart pointer in the "nil" state upon return.
 115   T* _retn ();
 116
 117   /// Equality operator allows the refcounted object to be used generically
 118   /// as a contained object
 119   bool operator== (const TAO_Intrusive_Ref_Count_Handle& h) const;
 120
 121 private:
 122   /// Claim a "copy" of the reference-counted object by adding
 123   /// one to its reference counter.  Do nothing if this smart pointer
 124   /// object is currently in the "nil" state.
 125   void claim ();
 126
 127   /// Drop our "copy" of the reference-counted object by removing
 128   /// one from its reference counter.  Do nothing if this smart pointer
 129   /// object is currently in the "nil" state.
 130   /// Note that this method will always leave this smart pointer
 131   /// in the "nil" state upon its return.
 132   void drop ();
 133
 134   /// The underlying pointer to the (intrusively) reference-counted object.
 135   /// Set to 0 when this smart pointer is in the "nil" state.  Otherwise,
 136   /// this smart pointer always owns a (reference-counted) "copy" of the
 137   /// object pointed to by the ptr_ data member.
 138   T* ptr_;
 139 };
 140
 141 TAO_END_VERSIONED_NAMESPACE_DECL
 142
 143 #if defined (__ACE_INLINE__)
 144 #include "tao/Intrusive_Ref_Count_Handle_T.inl"
 145 #endif /* __ACE_INLINE__ */
 146
 147 #include "tao/Intrusive_Ref_Count_Handle_T.cpp"
 148
 149 #include /**/ "ace/post.h"
 150
 151 #endif /* TAO_INTRUSIVE_REF_COUNT_HANDLE_T_H */