00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Intrusive_Ref_Count_Handle_T.h 00006 * 00007 * $Id: Intrusive_Ref_Count_Handle_T.h 74014 2006-08-14 13:52:22Z johnnyw $ 00008 * 00009 * @authors Tim Bradley <bradley_t@ociweb.com> 00010 */ 00011 //============================================================================= 00012 00013 #ifndef TAO_INTRUSIVE_REF_COUNT_HANDLE_T_H 00014 #define TAO_INTRUSIVE_REF_COUNT_HANDLE_T_H 00015 00016 #include /**/ "ace/pre.h" 00017 00018 #include "ace/config-all.h" 00019 00020 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00021 # pragma once 00022 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00023 00024 #include /**/ "tao/Versioned_Namespace.h" 00025 00026 TAO_BEGIN_VERSIONED_NAMESPACE_DECL 00027 00028 /** 00029 * @class TAO_Intrusive_Ref_Count_Handle<T> 00030 * 00031 * @brief Template class for smart-pointer to (intrusively) ref-counted object. 00032 * 00033 * This class behaves just like a xxx_var type behaves. The only significant 00034 * difference is that this class provides a "bool is_nil() const" method, 00035 * and xxx_var types don't (they use the "bool CORBA::is_nil(xxx_ptr ptr)" 00036 * method instead). For example, 00037 * 00038 * typedef TAO_Intrusive_Ref_Count_Handle<PortableServer::ServantBase> 00039 * MyServantBase_var; 00040 * 00041 * The MyServantBase_var and the PortableServer::ServantBase_var are 00042 * nearly idenitical. The only difference is that the MyServantBase_var 00043 * has a "isNil()" method that indicates whether or not the smart pointer 00044 * is in the 'nil' state or not. 00045 * 00046 * This class can be used to "safely" deal with an instance of a servant. 00047 * For example, we can use a single variable 00048 * TAO_Intrusive_Ref_Count_Handle<Foo_i> 00049 * 00050 * typedef TAO_Intrusive_Ref_Count_Handle<Foo_i> Foo_i_var; 00051 * Foo_i_var servant_; 00052 * 00053 * instead of using two variables 00054 * 00055 * PortableServer::ServantBase_var servant_holder_; 00056 * Foo_i* servant_; 00057 00058 * to deal with the servant memory. 00059 * 00060 * The Foo_i_var type does everything that the PortableServer::ServantBase_var 00061 * type does. In addition, the Foo_i_var type can provide access to the servant 00062 * as derived class via the arrow operator. 00063 */ 00064 template <typename T> 00065 class TAO_Intrusive_Ref_Count_Handle 00066 { 00067 public: 00068 00069 /// Default Constructor - enters the "nil" state. 00070 TAO_Intrusive_Ref_Count_Handle (void); 00071 00072 /// Ctor - By default, takes ownership of passed-in "copy" of reference 00073 /// to T. But the second argument (bool) can be changed from 00074 /// the default value of 'true' to the non-default value of 'false'. 00075 /// The second argument dictates whether or not this handle object 00076 /// should take ownership of the passed-in pointer to the T object. 00077 /// By default, it takes ownership, leaving the reference counter 00078 /// of the T object unchanged. When it is instructed to not take 00079 /// ownership (false value for second arg), then the reference 00080 /// counter of the T object will be incremented so that this 00081 /// handle object has its own "copy". 00082 TAO_Intrusive_Ref_Count_Handle (T* p, bool take_ownership = true); 00083 00084 /// Copy Constructor - claims a "copy" of rhs object's reference to T. 00085 TAO_Intrusive_Ref_Count_Handle (const TAO_Intrusive_Ref_Count_Handle& b); 00086 00087 /// Destructor 00088 ~TAO_Intrusive_Ref_Count_Handle (void); 00089 00090 /// Assignment Operator with T* argument. 00091 /// Takes ownership of passed-in "copy" of reference to T. 00092 TAO_Intrusive_Ref_Count_Handle& operator= (T* p); 00093 00094 /// Assignment Operator with const TAO_Smart_Ptr<T>& argument. 00095 /// Claims a "copy" of rhs object's reference to T. 00096 TAO_Intrusive_Ref_Count_Handle& operator= 00097 (const TAO_Intrusive_Ref_Count_Handle& b); 00098 00099 /// Const Accessor to underlying pointer (T*) using arrow (->) operator. 00100 T* operator->() const; 00101 00102 /// Returns true if underlying pointer is NULL (0). 00103 /// Returns false otherwise. 00104 bool is_nil (void) const; 00105 00106 /// Used to pass the underlying pointer as an "IN" argument to a method. 00107 T* in (void) const; 00108 00109 /// Used to pass the underlying pointer as an "IN/OUT" argument to a method. 00110 T*& inout (void); 00111 00112 /// Used to pass the underlying pointer as an "OUT" argument to a method. 00113 T*& out (void); 00114 00115 /// Used to take-away the underlying pointer from this smart pointer object. 00116 /// Caller becomes responsibe for the returned "copy" to the reference. 00117 /// Always leaves the smart pointer in the "nil" state upon return. 00118 T* _retn (void); 00119 00120 00121 private: 00122 00123 /// Claim a "copy" of the reference-counted object by adding 00124 /// one to its reference counter. Do nothing if this smart pointer 00125 /// object is currently in the "nil" state. 00126 void claim (void); 00127 00128 /// Drop our "copy" of the reference-counted object by removing 00129 /// one from its reference counter. Do nothing if this smart pointer 00130 /// object is currently in the "nil" state. 00131 /// Note that this method will always leave this smart pointer 00132 /// in the "nil" state upon its return. 00133 void drop (void); 00134 00135 00136 /// The underlying pointer to the (intrusively) reference-counted object. 00137 /// Set to 0 when this smart pointer is in the "nil" state. Otherwise, 00138 /// this smart pointer always owns a (reference-counted) "copy" of the 00139 /// object pointed to by the ptr_ data member. 00140 T* ptr_; 00141 }; 00142 00143 TAO_END_VERSIONED_NAMESPACE_DECL 00144 00145 #if defined (__ACE_INLINE__) 00146 #include "tao/Intrusive_Ref_Count_Handle_T.inl" 00147 #endif /* __ACE_INLINE__ */ 00148 00149 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) 00150 #include "tao/Intrusive_Ref_Count_Handle_T.cpp" 00151 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */ 00152 00153 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA) 00154 #pragma implementation ("Intrusive_Ref_Count_Handle_T.cpp") 00155 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */ 00156 00157 #include /**/ "ace/post.h" 00158 00159 #endif /* TAO_INTRUSIVE_REF_COUNT_HANDLE_T_H */