00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Bound_Ptr.h 00006 * 00007 * Bound_Ptr.h,v 4.10 2005/10/28 16:14:51 ossama Exp 00008 * 00009 * @author Christopher Kohlhoff <chris@kohlhoff.com> 00010 */ 00011 //============================================================================= 00012 00013 #ifndef ACE_BOUND_PTR_H 00014 #define ACE_BOUND_PTR_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 "ace/Auto_Ptr.h" 00025 00026 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00027 00028 /** 00029 * @class ACE_Bound_Ptr_Counter 00030 * 00031 * @brief An ACE_Bound_Ptr_Counter<ACE_LOCK> object encapsulates an 00032 * object reference count. 00033 * 00034 * Do not use this class directly, use ACE_Strong_Bound_Ptr or 00035 * ACE_Weak_Bound_Ptr instead. 00036 */ 00037 template <class ACE_LOCK> 00038 class ACE_Bound_Ptr_Counter 00039 { 00040 public: 00041 /// Declare the dynamic allocation hooks. 00042 ACE_ALLOC_HOOK_DECLARE; 00043 00044 ACE_Bound_Ptr_Counter (int init_obj_ref_count = 0); 00045 ~ACE_Bound_Ptr_Counter (void); 00046 00047 /// Create a ACE_Bound_Ptr_Counter<ACE_LOCK> and initialize the 00048 /// reference count to indicate ownership by a strong pointer. 00049 static ACE_Bound_Ptr_Counter<ACE_LOCK> *create_strong (void); 00050 00051 /// Increase both the object and counter reference counts and return 00052 /// the new object reference count. A return value of -1 indicates 00053 /// that the object has already been destroyed. 00054 static int attach_strong (ACE_Bound_Ptr_Counter<ACE_LOCK> *counter); 00055 00056 /// Decreases both the object and counter reference counts and 00057 /// deletes whichever has no more references. Returns the new object 00058 /// reference count. 00059 static int detach_strong (ACE_Bound_Ptr_Counter<ACE_LOCK> *counter); 00060 00061 /// Create a ACE_Bound_Ptr_Counter<ACE_LOCK> and initialize the 00062 /// reference count to indicate no ownership. 00063 static ACE_Bound_Ptr_Counter<ACE_LOCK> *create_weak (void); 00064 00065 /// Increase the counter reference count and return argument. 00066 static void attach_weak (ACE_Bound_Ptr_Counter<ACE_LOCK> *counter); 00067 00068 /// Decreases the counter reference count and deletes the counter if 00069 /// it has no more references. 00070 static void detach_weak (ACE_Bound_Ptr_Counter<ACE_LOCK> *counter); 00071 00072 /// Determine whether the object has been deleted. 00073 static int object_was_deleted (ACE_Bound_Ptr_Counter<ACE_LOCK> *counter); 00074 00075 private: 00076 00077 /// Allocate a new ACE_Bound_Ptr_Counter<ACE_LOCK> instance, 00078 /// returning NULL if it cannot be created. 00079 static ACE_Bound_Ptr_Counter<ACE_LOCK> *internal_create (int init_obj_ref_count); 00080 00081 private: 00082 00083 /// Reference count of underlying object. Is set to -1 once the 00084 /// object has been destroyed to indicate to all weak pointers that 00085 /// it is no longer valid. 00086 int obj_ref_count_; 00087 00088 /// Reference count of this counter. 00089 int self_ref_count_; 00090 00091 /// Mutex variable to synchronize access to the reference counts. 00092 ACE_LOCK lock_; 00093 }; 00094 00095 // Forward decl. 00096 template <class X, class ACE_LOCK> class ACE_Weak_Bound_Ptr; 00097 00098 /** 00099 * @class ACE_Strong_Bound_Ptr 00100 * 00101 * @brief This class implements support for a reference counted 00102 * pointer. 00103 * 00104 * Assigning or copying instances of an ACE_Strong_Bound_Ptr will 00105 * automatically increment the reference count of the underlying object. 00106 * When the last instance of an ACE_Strong_Bound_Ptr that references a 00107 * particular object is destroyed or overwritten, it will invoke delete 00108 * on its underlying pointer. 00109 */ 00110 template <class X, class ACE_LOCK> 00111 class ACE_Strong_Bound_Ptr 00112 { 00113 public: 00114 /// Constructor that initializes an ACE_Strong_Bound_Ptr to point to the 00115 /// object <p> immediately. 00116 explicit ACE_Strong_Bound_Ptr (X *p = 0); 00117 00118 /// Constructor that initializes an ACE_Strong_Bound_Ptr by stealing 00119 /// ownership of an object from an auto_ptr. 00120 explicit ACE_Strong_Bound_Ptr (auto_ptr<X> p); 00121 00122 /// Copy constructor binds <this> and <r> to the same object. 00123 ACE_Strong_Bound_Ptr (const ACE_Strong_Bound_Ptr<X, ACE_LOCK> &r); 00124 00125 /// Constructor binds <this> and <r> to the same object. 00126 ACE_Strong_Bound_Ptr (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r); 00127 00128 /// Destructor. 00129 ~ACE_Strong_Bound_Ptr (void); 00130 00131 /// Assignment operator that binds <this> and <r> to the same object. 00132 void operator = (const ACE_Strong_Bound_Ptr<X, ACE_LOCK> &r); 00133 00134 /// Assignment operator that binds <this> and <r> to the same object. 00135 void operator = (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r); 00136 00137 /// Equality operator that returns @c true if both 00138 /// ACE_Strong_Bound_Ptr instances point to the same underlying 00139 /// object. 00140 /** 00141 * @note It also returns @c true if both objects have just been 00142 * instantiated and not used yet. 00143 */ 00144 bool operator == (const ACE_Strong_Bound_Ptr<X, ACE_LOCK> &r) const; 00145 00146 /// Equality operator that returns true if the ACE_Strong_Bound_Ptr 00147 /// and ACE_Weak_Bound_Ptr objects point to the same underlying 00148 /// object. 00149 /** 00150 * @note It also returns @c true if both objects have just been 00151 * instantiated and not used yet. 00152 */ 00153 bool operator == (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r) const; 00154 00155 /// Equality operator that returns @c true if the 00156 /// ACE_Strong_Bound_Ptr and the raw pointer point to the same 00157 /// underlying object. 00158 bool operator == (X *p) const; 00159 00160 /// Inequality operator, which is the opposite of equality. 00161 bool operator != (const ACE_Strong_Bound_Ptr<X, ACE_LOCK> &r) const; 00162 00163 /// Inequality operator, which is the opposite of equality. 00164 bool operator != (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r) const; 00165 00166 /// Inequality operator, which is the opposite of equality. 00167 bool operator != (X *p) const; 00168 00169 /// Redirection operator 00170 X *operator-> (void) const; 00171 00172 /// Dereference operator 00173 X &operator * (void) const; 00174 00175 /// Get the pointer value. 00176 X *get (void) const; 00177 00178 /// Resets the ACE_Strong_Bound_Ptr to refer to a different 00179 /// underlying object. 00180 void reset (X *p = 0); 00181 00182 /// Resets the ACE_Strong_Bound_Ptr to refer to a different 00183 /// underlying object, ownership of which is stolen from the 00184 /// auto_ptr. 00185 void reset (auto_ptr<X> p); 00186 00187 /// Allows us to check for NULL on all ACE_Strong_Bound_Ptr 00188 /// objects. 00189 int null (void) const; 00190 00191 /// Declare the dynamic allocation hooks. 00192 ACE_ALLOC_HOOK_DECLARE; 00193 00194 private: 00195 friend class ACE_Weak_Bound_Ptr<X, ACE_LOCK>; 00196 00197 /// The ACE_Bound_Ptr_Counter type. 00198 typedef ACE_Bound_Ptr_Counter<ACE_LOCK> COUNTER; 00199 00200 /// The reference counter. 00201 COUNTER *counter_; 00202 00203 /// The underlying object. 00204 X *ptr_; 00205 }; 00206 00207 /** 00208 * @class ACE_Weak_Bound_Ptr 00209 * 00210 * @brief This class implements support for a weak pointer that complements 00211 * ACE_Strong_Bound_Ptr. 00212 * 00213 * Unlike ACE_Strong_Bound_Ptr, assigning or copying instances of an 00214 * ACE_Weak_Bound_Ptr will not automatically increment the reference 00215 * count of the underlying object. What ACE_Weak_Bound_Ptr does is 00216 * preserve the knowledge that the object is in fact reference 00217 * counted, and thus provides an alternative to raw pointers where 00218 * non-ownership associations must be maintained. When the last 00219 * instance of an ACE_Strong_Bound_Ptr that references a particular 00220 * object is destroyed or overwritten, the corresponding 00221 * ACE_Weak_Bound_Ptr instances are set to NULL. 00222 */ 00223 template <class X, class ACE_LOCK> 00224 class ACE_Weak_Bound_Ptr 00225 { 00226 public: 00227 /// Constructor that initializes an ACE_Weak_Bound_Ptr to point to 00228 /// the object <p> immediately. 00229 explicit ACE_Weak_Bound_Ptr (X *p = 0); 00230 00231 /// Copy constructor binds <this> and <r> to the same object. 00232 ACE_Weak_Bound_Ptr (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r); 00233 00234 /// Constructor binds <this> and <r> to the same object. 00235 ACE_Weak_Bound_Ptr (const ACE_Strong_Bound_Ptr<X, ACE_LOCK> &r); 00236 00237 /// Destructor. 00238 ~ACE_Weak_Bound_Ptr (void); 00239 00240 /// Assignment operator that binds <this> and <r> to the same object. 00241 void operator = (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r); 00242 00243 /// Assignment operator that binds <this> and <r> to the same object. 00244 void operator = (const ACE_Strong_Bound_Ptr<X, ACE_LOCK> &r); 00245 00246 /// Equality operator that returns @c true if both 00247 /// ACE_Weak_Bound_Ptr objects point to the same underlying object. 00248 /** 00249 * @note It also returns @c true if both objects have just been 00250 * instantiated and not used yet. 00251 */ 00252 bool operator == (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r) const; 00253 00254 /// Equality operator that returns @c true if the ACE_Weak_Bound_Ptr 00255 /// and ACE_Strong_Bound_Ptr objects point to the same underlying 00256 /// object. 00257 /** 00258 * @note It also returns @c true if both objects have just been 00259 * instantiated and not used yet. 00260 */ 00261 bool operator == (const ACE_Strong_Bound_Ptr<X, ACE_LOCK> &r) const; 00262 00263 /// Equality operator that returns @c true if the ACE_Weak_Bound_Ptr 00264 /// and the raw pointer point to the same underlying object. 00265 bool operator == (X *p) const; 00266 00267 /// Inequality operator, which is the opposite of equality. 00268 bool operator != (const ACE_Weak_Bound_Ptr<X, ACE_LOCK> &r) const; 00269 00270 /// Inequality operator, which is the opposite of equality. 00271 bool operator != (const ACE_Strong_Bound_Ptr<X, ACE_LOCK> &r) const; 00272 00273 /// Inequality operator, which is the opposite of equality. 00274 bool operator != (X *p) const; 00275 00276 /// Redirection operator. 00277 /** 00278 * It returns a temporary strong pointer and makes use of the 00279 * chaining properties of operator-> to ensure that the underlying 00280 * object does not disappear while you are using it. If you are 00281 * certain of the lifetimes of the object, and do not want to incur 00282 * the locking overhead, then use the unsafe_get method instead. 00283 */ 00284 ACE_Strong_Bound_Ptr<X, ACE_LOCK> operator-> (void) const; 00285 00286 /// Obtain a strong pointer corresponding to this weak pointer. This 00287 /// function is useful to create a temporary strong pointer for 00288 /// conversion to a reference. 00289 ACE_Strong_Bound_Ptr<X, ACE_LOCK> strong (void) const; 00290 00291 /// Get the pointer value. Warning: this does not affect the 00292 /// reference count of the underlying object, so it may disappear on 00293 /// you while you are using it if you are not careful. 00294 X *unsafe_get (void) const; 00295 00296 /// Resets the ACE_Weak_Bound_Ptr to refer to a different underlying 00297 /// object. 00298 void reset (X *p = 0); 00299 00300 /// Increment the reference count on the underlying object. 00301 /** 00302 * Returns the new reference count on the object. This function may 00303 * be used to integrate the bound pointers into an external 00304 * reference counting mechanism such as those used by COM or CORBA 00305 * servants. 00306 */ 00307 int add_ref (void); 00308 00309 /// Decrement the reference count on the underlying object, which is deleted 00310 /// if the count has reached zero. 00311 /** 00312 * Returns the new reference count on the object. This function may 00313 * be used to integrate the bound pointers into an external 00314 * reference counting mechanism such as those used by COM or CORBA 00315 * servants. 00316 */ 00317 int remove_ref (void); 00318 00319 /// Allows us to check for NULL on all ACE_Weak_Bound_Ptr objects. 00320 int null (void) const; 00321 00322 /// Declare the dynamic allocation hooks. 00323 ACE_ALLOC_HOOK_DECLARE; 00324 00325 private: 00326 friend class ACE_Strong_Bound_Ptr<X, ACE_LOCK>; 00327 00328 /// The ACE_Bound_Ptr_Counter type. 00329 typedef ACE_Bound_Ptr_Counter<ACE_LOCK> COUNTER; 00330 00331 /// The reference counter. 00332 COUNTER *counter_; 00333 00334 /// The underlying object. 00335 X *ptr_; 00336 }; 00337 00338 ACE_END_VERSIONED_NAMESPACE_DECL 00339 00340 #include "ace/Bound_Ptr.inl" 00341 00342 #include /**/ "ace/post.h" 00343 00344 #endif /* ACE_BOUND_PTR_H */