include/ptlib/smartptr.h

   1 #ifndef _PSMARTPTR_H
   2 #define _PSMARTPTR_H
   3
   4 #include <ptlib.h>
   5 #include <ptlib/object.h>
   6
   7 ///////////////////////////////////////////////////////////////////////////////
   8 // "Smart" pointers.
   9
  10 /** This is the base class for objects that use the {\it smart pointer} system.
  11    In conjunction with the #PSmartPointer# class, this class creates
  12    objects that can have the automatic deletion of the object instance when
  13    there are no more smart pointer instances pointing to it.
  14
  15    A #PSmartObject# carries the reference count that the #PSmartPointer#
  16    requires to determine if the pointer is needed any more and should be
  17    deleted.
  18  */
  19 class PSmartObject : public PObject
  20 {
  21   PCLASSINFO(PSmartObject, PObject);
  22
  23   public:
  24     /** Construct a new smart object, subject to a #PSmartPointer# instance
  25        referencing it.
  26      */
  27     PSmartObject()
  28       :referenceCount(1) { }
  29
  30   protected:
  31     /** Count of number of instances of #PSmartPointer# that currently
  32        reference the object instance.
  33      */
  34     PAtomicInteger referenceCount;
  35
  36
  37   friend class PSmartPointer;
  38 };
  39
  40
  41 /** This is the class for pointers to objects that use the {\it smart pointer}
  42    system. In conjunction with the #PSmartObject# class, this class
  43    references objects that can have the automatic deletion of the object
  44    instance when there are no more smart pointer instances pointing to it.
  45
  46    A PSmartPointer carries the pointer to a #PSmartObject# instance which
  47    contains a reference count. Assigning or copying instances of smart pointers
  48    will automatically increment and decrement the reference count. When the
  49    last instance that references a #PSmartObject# instance is destroyed or
  50    overwritten, the #PSmartObject# is deleted.
  51
  52    A NULL value is possible for a smart pointer. It can be detected via the
  53    #IsNULL()# function.
  54  */
  55 class PSmartPointer : public PObject
  56 {
  57   PCLASSINFO(PSmartPointer, PObject);
  58
  59   public:
  60   /**@name Construction */
  61   //@{
  62     /** Create a new smart pointer instance and have it point to the specified
  63        #PSmartObject# instance.
  64      */
  65     PSmartPointer(
  66       PSmartObject * obj = NULL   /// Smart object to point to.
  67     ) { object = obj; }
  68
  69     /** Create a new smart pointer and point it at the data pointed to by the
  70        #ptr# parameter. The reference count for the object being
  71        pointed at is incremented.
  72      */
  73     PSmartPointer(
  74       const PSmartPointer & ptr  /// Smart pointer to make a copy of.
  75     );
  76
  77     /** Destroy the smart pointer and decrement the reference count on the
  78        object being pointed to. If there are no more references then the
  79        object is deleted.
  80      */
  81     virtual ~PSmartPointer();
  82
  83     /** Assign this pointer to the value specified in the #ptr#
  84        parameter.
  85
  86        The previous object being pointed to has its reference count
  87        decremented as this will no longer point to it. If there are no more
  88        references then the object is deleted.
  89
  90        The new object being pointed to after the assignment has its reference
  91        count incremented.
  92      */
  93     PSmartPointer & operator=(
  94       const PSmartPointer & ptr  /// Smart pointer to assign.
  95     );
  96   //@}
  97
  98   /**@name Overrides from class PObject */
  99   //@{
 100     /** Determine the relative rank of the pointers. This is identical to
 101        determining the relative rank of the integer values represented by the
 102        memory pointers.
 103
 104        @return
 105        #EqualTo# if objects point to the same object instance,
 106        otherwise #LessThan# and #GreaterThan# may be
 107        returned depending on the relative values of the memory pointers.
 108      */
 109     virtual Comparison Compare(
 110       const PObject & obj   // Other smart pointer to compare against.
 111     ) const;
 112   //@}
 113
 114   /**@name Pointer access functions */
 115   //@{
 116     /** Determine if the smart pointer has been set to point to an actual
 117        object instance.
 118
 119        @return
 120        TRUE if the pointer is NULL.
 121      */
 122     BOOL IsNULL() const { return object == NULL; }
 123
 124     /** Get the current value if the internal smart object pointer.
 125
 126        @return
 127        pointer to object instance.
 128      */
 129     PSmartObject * GetObject() const { return object; }
 130   //@}
 131
 132   protected:
 133     // Member variables
 134     /// Object the smart pointer points to.
 135     PSmartObject * object;
 136 };
 137
 138
 139 /** This macro is used to declare a smart pointer class members.
 140 The class #cls# is the smart pointer, descended from the #par# class, to the
 141 #type# class.
 142
 143 The macro declares in the class the following functions:
 144 \begin{verbatim}
 145       PCLASSINFO(cls, par);
 146         Standard class info.
 147
 148       type * operator->() const;
 149         Access to the members of the smart object in the smart pointer.
 150
 151       type & operator*() const;
 152         Access to the value of the smart object in the smart pointer.
 153 \end{verbatim}
 154 */
 155 #define PSMART_POINTER_INFO(cls, par, type) \
 156   PCLASSINFO(cls, par) \
 157   public: \
 158     type * operator->() const \
 159       { return (type *)PAssertNULL(object); } \
 160     type & operator*() const \
 161       { return *(type *)PAssertNULL(object); } \
 162     operator type*() const \
 163       { return (type *)object; }
 164
 165 #endif
 166