Bound_Ptr.h

Go to the documentation of this file.
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 */

Generated on Thu Nov 9 09:41:47 2006 for ACE by doxygen 1.3.6