ACE/ace/Refcounted_Auto_Ptr.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Refcounted_Auto_Ptr.h
   6  *
   7  *  @author John Tucker <JTucker@infoglide.com>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_REFCOUNTED_AUTO_PTR_H
  12 #define ACE_REFCOUNTED_AUTO_PTR_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include "ace/Auto_Ptr.h"
  17 #include "ace/Atomic_Op.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24
  25 // Forward decl.
  26 template <class X, class ACE_LOCK> class ACE_Refcounted_Auto_Ptr_Rep;
  27 template <class X, class ACE_LOCK> class ACE_Refcounted_Auto_Ptr;
  28
  29 /**
  30  * @class ACE_Refcounted_Auto_Ptr
  31  *
  32  * @brief This class implements support for a reference counted auto_ptr.
  33  * Assigning or copying instances of an ACE_Refcounted_Auto_Ptr
  34  * will automatically increment the reference count. When the last
  35  * instance that references a ACE_Refcounted_Auto_Ptr instance is
  36  * destroyed or overwritten, it will invoke delete on its underlying
  37  * pointer.
  38  *
  39  * The ACE_Refcounted_Auto_Ptr works by maintaining a reference to a
  40  * separate representation object, ACE_Refcounted_Auto_Ptr_Rep. That
  41  * separate representation object contains the reference count and
  42  * the actual pointer value.
  43  */
  44 template <class X, class ACE_LOCK>
  45 class ACE_Refcounted_Auto_Ptr
  46 {
  47 public:
  48   /// Constructor that initializes an ACE_Refcounted_Auto_Ptr to
  49   /// the specified pointer value.
  50   explicit ACE_Refcounted_Auto_Ptr (X *p = 0);
  51
  52   /// Copy constructor binds the new ACE_Refcounted_Auto_Ptr to the
  53   /// representation object referenced by @a r.
  54   /// An ACE_Refcounted_Auto_Ptr_Rep is created if necessary.
  55   ACE_Refcounted_Auto_Ptr (const ACE_Refcounted_Auto_Ptr<X, ACE_LOCK> &r);
  56
  57   /// Destructor. Releases the reference to the underlying representation.
  58   /// If the release of that reference causes its reference count to reach 0,
  59   /// the representation object will also be destroyed.
  60   virtual ~ACE_Refcounted_Auto_Ptr (void);
  61
  62   /// Assignment operator that binds the current object and @a r to the same
  63   /// ACE_Refcounted_Auto_Ptr_Rep. An ACE_Refcounted_Auto_Ptr_Rep
  64   /// is created if necessary.
  65   void operator = (const ACE_Refcounted_Auto_Ptr<X, ACE_LOCK> &r);
  66
  67   /// Equality operator that returns @c true if both
  68   /// ACE_Refcounted_Auto_Ptr objects point to the same underlying
  69   /// representation. It does not compare the actual pointers.
  70   /**
  71    * @note It also returns @c true if both objects have just been
  72    *       instantiated and not used yet.
  73    */
  74   bool operator == (const ACE_Refcounted_Auto_Ptr<X, ACE_LOCK> &r) const;
  75
  76   /// Inequality operator, which is the opposite of equality.
  77   bool operator != (const ACE_Refcounted_Auto_Ptr<X, ACE_LOCK> &r) const;
  78
  79   /// Redirection operator
  80   X *operator-> (void) const;
  81
  82   /// Accessor method.
  83   X &operator *() const;
  84
  85   /// Check rep easily.
  86   bool operator !() const;
  87
  88   /// Check rep easily.
  89   operator bool () const;
  90
  91   /// Releases the reference to the underlying representation object.
  92   /// @retval The pointer value prior to releasing it.
  93   X *release (void);
  94
  95   /// Releases the current pointer value and then sets a new
  96   /// pointer value specified by @a p.
  97   void reset (X *p = 0);
  98
  99   /// Get the pointer value.
 100   X *get (void) const;
 101
 102   /// Get the reference count value.
 103   long count (void) const;
 104
 105   /// Returns @c true if this object does not contain a valid pointer.
 106   bool null (void) const;
 107
 108   /// Declare the dynamic allocation hooks.
 109   ACE_ALLOC_HOOK_DECLARE;
 110
 111 protected:
 112   /// the ACE_Refcounted_Auto_Ptr_Rep
 113   typedef ACE_Refcounted_Auto_Ptr_Rep<X, ACE_LOCK> AUTO_REFCOUNTED_PTR_REP;
 114
 115   /// Protect operations on the ACE_Refcounted_Auto_Ptr.
 116   AUTO_REFCOUNTED_PTR_REP *rep_;
 117 };
 118
 119 /**
 120  * @class ACE_Refcounted_Auto_Ptr_Rep
 121  *
 122  * @brief An ACE_Refcounted_Auto_Ptr_Rep object encapsulates a pointer
 123  * to an object of type X. It uses a lock object of type ACE_LOCK to protect
 124  * access to the reference count.
 125  *
 126  * @internal ACE_Refcounted_Auto_Ptr_Rep is used internally by the
 127  * ACE_Refcounted_Auto_Ptr class and is only accessible through it.
 128  */
 129 template <class X, class ACE_LOCK>
 130 class ACE_Refcounted_Auto_Ptr_Rep
 131 {
 132 private:
 133   friend class ACE_Refcounted_Auto_Ptr<X, ACE_LOCK>;
 134
 135   /// Get the pointer value.
 136   X *get (void) const;
 137
 138   /// Get the reference count value.
 139   long count (void) const;
 140
 141   /// Declare the dynamic allocation hooks.
 142   ACE_ALLOC_HOOK_DECLARE;
 143
 144   // = Encapsulate reference count and object lifetime of instances.
 145   // These methods must go after the others to work around a bug with
 146   // Borland's C++ Builder...
 147
 148   /// Allocate a new ACE_Refcounted_Auto_Ptr_Rep<X, ACE_LOCK> instance,
 149   /// returning NULL if it cannot be created.
 150   static ACE_Refcounted_Auto_Ptr_Rep<X, ACE_LOCK> *internal_create (X *p);
 151
 152   /// Create a ACE_Refcounted_Auto_Ptr_Rep<X, ACE_LOCK> and initialize
 153   /// the reference count.
 154   static ACE_Refcounted_Auto_Ptr_Rep<X, ACE_LOCK> *create (X *p);
 155
 156   /// Increase the reference count on @a rep.
 157   ///
 158   /// @retval @a rep if success, 0 if there's an error obtaining the lock
 159   ///         on @a rep.
 160   static ACE_Refcounted_Auto_Ptr_Rep<X, ACE_LOCK> *attach (ACE_Refcounted_Auto_Ptr_Rep<X, ACE_LOCK> *&rep);
 161
 162   /// Decreases the reference count and and deletes rep if there are no
 163   /// more references to rep.
 164   ///
 165   /// Precondition (rep != 0)
 166   static void detach (ACE_Refcounted_Auto_Ptr_Rep<X, ACE_LOCK> *&rep);
 167
 168   /// Pointer to the result.
 169   ACE_Auto_Basic_Ptr<X> ptr_;
 170
 171   /// Reference count.
 172   mutable ACE_Atomic_Op<ACE_LOCK, long> ref_count_;
 173
 174 private:
 175   // = Constructor and destructor private.
 176   ACE_Refcounted_Auto_Ptr_Rep (X *p = 0);
 177   ~ACE_Refcounted_Auto_Ptr_Rep (void);
 178 };
 179
 180 ACE_END_VERSIONED_NAMESPACE_DECL
 181
 182 #include "ace/Refcounted_Auto_Ptr.inl"
 183
 184 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 185 #include "ace/Refcounted_Auto_Ptr.cpp"
 186 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 187
 188 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 189 #pragma implementation ("Refcounted_Auto_Ptr.cpp")
 190 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 191
 192 #include /**/ "ace/post.h"
 193
 194 #endif /* ACE_REFCOUNTED_AUTO_PTR_H */