Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Bound_Ptr.h

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

Generated on Mon Jun 16 11:19:13 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002