juce/source/src/memory/juce_ReferenceCountedObject.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_REFERENCECOUNTEDOBJECT_JUCEHEADER__
  27 #define __JUCE_REFERENCECOUNTEDOBJECT_JUCEHEADER__
  28
  29 #include "juce_Atomic.h"
  30
  31
  32 //==============================================================================
  33 /**
  34     Adds reference-counting to an object.
  35
  36     To add reference-counting to a class, derive it from this class, and
  37     use the ReferenceCountedObjectPtr class to point to it.
  38
  39     e.g. @code
  40     class MyClass : public ReferenceCountedObject
  41     {
  42         void foo();
  43
  44         // This is a neat way of declaring a typedef for a pointer class,
  45         // rather than typing out the full templated name each time..
  46         typedef ReferenceCountedObjectPtr<MyClass> Ptr;
  47     };
  48
  49     MyClass::Ptr p = new MyClass();
  50     MyClass::Ptr p2 = p;
  51     p = nullptr;
  52     p2->foo();
  53     @endcode
  54
  55     Once a new ReferenceCountedObject has been assigned to a pointer, be
  56     careful not to delete the object manually.
  57
  58     This class uses an Atomic<int> value to hold the reference count, so that it
  59     the pointers can be passed between threads safely. For a faster but non-thread-safe
  60     version, use SingleThreadedReferenceCountedObject instead.
  61
  62     @see ReferenceCountedObjectPtr, ReferenceCountedArray, SingleThreadedReferenceCountedObject
  63 */
  64 class JUCE_API  ReferenceCountedObject
  65 {
  66 public:
  67     //==============================================================================
  68     /** Increments the object's reference count.
  69
  70         This is done automatically by the smart pointer, but is public just
  71         in case it's needed for nefarious purposes.
  72     */
  73     inline void incReferenceCount() noexcept
  74     {
  75         ++refCount;
  76     }
  77
  78     /** Decreases the object's reference count.
  79
  80         If the count gets to zero, the object will be deleted.
  81     */
  82     inline void decReferenceCount() noexcept
  83     {
  84         jassert (getReferenceCount() > 0);
  85
  86         if (--refCount == 0)
  87             delete this;
  88     }
  89
  90     /** Returns the object's current reference count. */
  91     inline int getReferenceCount() const noexcept       { return refCount.get(); }
  92
  93
  94 protected:
  95     //==============================================================================
  96     /** Creates the reference-counted object (with an initial ref count of zero). */
  97     ReferenceCountedObject()
  98     {
  99     }
 100
 101     /** Destructor. */
 102     virtual ~ReferenceCountedObject()
 103     {
 104         // it's dangerous to delete an object that's still referenced by something else!
 105         jassert (getReferenceCount() == 0);
 106     }
 107
 108 private:
 109     //==============================================================================
 110     Atomic <int> refCount;
 111 };
 112
 113
 114 //==============================================================================
 115 /**
 116     Adds reference-counting to an object.
 117
 118     This is efectively a version of the ReferenceCountedObject class, but which
 119     uses a non-atomic counter, and so is not thread-safe (but which will be more
 120     efficient).
 121     For more details on how to use it, see the ReferenceCountedObject class notes.
 122
 123     @see ReferenceCountedObject, ReferenceCountedObjectPtr, ReferenceCountedArray
 124 */
 125 class JUCE_API  SingleThreadedReferenceCountedObject
 126 {
 127 public:
 128     //==============================================================================
 129     /** Increments the object's reference count.
 130
 131         This is done automatically by the smart pointer, but is public just
 132         in case it's needed for nefarious purposes.
 133     */
 134     inline void incReferenceCount() noexcept
 135     {
 136         ++refCount;
 137     }
 138
 139     /** Decreases the object's reference count.
 140
 141         If the count gets to zero, the object will be deleted.
 142     */
 143     inline void decReferenceCount() noexcept
 144     {
 145         jassert (getReferenceCount() > 0);
 146
 147         if (--refCount == 0)
 148             delete this;
 149     }
 150
 151     /** Returns the object's current reference count. */
 152     inline int getReferenceCount() const noexcept       { return refCount; }
 153
 154
 155 protected:
 156     //==============================================================================
 157     /** Creates the reference-counted object (with an initial ref count of zero). */
 158     SingleThreadedReferenceCountedObject() : refCount (0)  {}
 159
 160     /** Destructor. */
 161     virtual ~SingleThreadedReferenceCountedObject()
 162     {
 163         // it's dangerous to delete an object that's still referenced by something else!
 164         jassert (getReferenceCount() == 0);
 165     }
 166
 167 private:
 168     //==============================================================================
 169     int refCount;
 170 };
 171
 172
 173 //==============================================================================
 174 /**
 175     A smart-pointer class which points to a reference-counted object.
 176
 177     The template parameter specifies the class of the object you want to point to - the easiest
 178     way to make a class reference-countable is to simply make it inherit from ReferenceCountedObject,
 179     but if you need to, you could roll your own reference-countable class by implementing a pair of
 180     mathods called incReferenceCount() and decReferenceCount().
 181
 182     When using this class, you'll probably want to create a typedef to abbreviate the full
 183     templated name - e.g.
 184     @code typedef ReferenceCountedObjectPtr<MyClass> MyClassPtr;@endcode
 185
 186     @see ReferenceCountedObject, ReferenceCountedObjectArray
 187 */
 188 template <class ReferenceCountedObjectClass>
 189 class ReferenceCountedObjectPtr
 190 {
 191 public:
 192     /** The class being referenced by this pointer. */
 193     typedef ReferenceCountedObjectClass ReferencedType;
 194
 195     //==============================================================================
 196     /** Creates a pointer to a null object. */
 197     inline ReferenceCountedObjectPtr() noexcept
 198         : referencedObject (nullptr)
 199     {
 200     }
 201
 202     /** Creates a pointer to an object.
 203
 204         This will increment the object's reference-count if it is non-null.
 205     */
 206     inline ReferenceCountedObjectPtr (ReferenceCountedObjectClass* const refCountedObject) noexcept
 207         : referencedObject (refCountedObject)
 208     {
 209         if (refCountedObject != nullptr)
 210             refCountedObject->incReferenceCount();
 211     }
 212
 213     /** Copies another pointer.
 214
 215         This will increment the object's reference-count (if it is non-null).
 216     */
 217     inline ReferenceCountedObjectPtr (const ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& other) noexcept
 218         : referencedObject (other.referencedObject)
 219     {
 220         if (referencedObject != nullptr)
 221             referencedObject->incReferenceCount();
 222     }
 223
 224     /** Changes this pointer to point at a different object.
 225
 226         The reference count of the old object is decremented, and it might be
 227         deleted if it hits zero. The new object's count is incremented.
 228     */
 229     ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& operator= (const ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& other)
 230     {
 231         ReferenceCountedObjectClass* const newObject = other.referencedObject;
 232
 233         if (newObject != referencedObject)
 234         {
 235             if (newObject != nullptr)
 236                 newObject->incReferenceCount();
 237
 238             ReferenceCountedObjectClass* const oldObject = referencedObject;
 239             referencedObject = newObject;
 240
 241             if (oldObject != nullptr)
 242                 oldObject->decReferenceCount();
 243         }
 244
 245         return *this;
 246     }
 247
 248     /** Changes this pointer to point at a different object.
 249
 250         The reference count of the old object is decremented, and it might be
 251         deleted if it hits zero. The new object's count is incremented.
 252     */
 253     ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& operator= (ReferenceCountedObjectClass* const newObject)
 254     {
 255         if (referencedObject != newObject)
 256         {
 257             if (newObject != nullptr)
 258                 newObject->incReferenceCount();
 259
 260             ReferenceCountedObjectClass* const oldObject = referencedObject;
 261             referencedObject = newObject;
 262
 263             if (oldObject != nullptr)
 264                 oldObject->decReferenceCount();
 265         }
 266
 267         return *this;
 268     }
 269
 270     /** Destructor.
 271
 272         This will decrement the object's reference-count, and may delete it if it
 273         gets to zero.
 274     */
 275     inline ~ReferenceCountedObjectPtr()
 276     {
 277         if (referencedObject != nullptr)
 278             referencedObject->decReferenceCount();
 279     }
 280
 281     /** Returns the object that this pointer references.
 282         The pointer returned may be zero, of course.
 283     */
 284     inline operator ReferenceCountedObjectClass*() const noexcept
 285     {
 286         return referencedObject;
 287     }
 288
 289     // the -> operator is called on the referenced object
 290     inline ReferenceCountedObjectClass* operator->() const noexcept
 291     {
 292         return referencedObject;
 293     }
 294
 295     /** Returns the object that this pointer references.
 296         The pointer returned may be zero, of course.
 297     */
 298     inline ReferenceCountedObjectClass* getObject() const noexcept
 299     {
 300         return referencedObject;
 301     }
 302
 303 private:
 304     //==============================================================================
 305     ReferenceCountedObjectClass* referencedObject;
 306 };
 307
 308
 309 /** Compares two ReferenceCountedObjectPointers. */
 310 template <class ReferenceCountedObjectClass>
 311 bool operator== (const ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& object1, ReferenceCountedObjectClass* const object2) noexcept
 312 {
 313     return object1.getObject() == object2;
 314 }
 315
 316 /** Compares two ReferenceCountedObjectPointers. */
 317 template <class ReferenceCountedObjectClass>
 318 bool operator== (const ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& object1, const ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& object2) noexcept
 319 {
 320     return object1.getObject() == object2.getObject();
 321 }
 322
 323 /** Compares two ReferenceCountedObjectPointers. */
 324 template <class ReferenceCountedObjectClass>
 325 bool operator== (ReferenceCountedObjectClass* object1, ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& object2) noexcept
 326 {
 327     return object1 == object2.getObject();
 328 }
 329
 330 /** Compares two ReferenceCountedObjectPointers. */
 331 template <class ReferenceCountedObjectClass>
 332 bool operator!= (const ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& object1, const ReferenceCountedObjectClass* object2) noexcept
 333 {
 334     return object1.getObject() != object2;
 335 }
 336
 337 /** Compares two ReferenceCountedObjectPointers. */
 338 template <class ReferenceCountedObjectClass>
 339 bool operator!= (const ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& object1, ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& object2) noexcept
 340 {
 341     return object1.getObject() != object2.getObject();
 342 }
 343
 344 /** Compares two ReferenceCountedObjectPointers. */
 345 template <class ReferenceCountedObjectClass>
 346 bool operator!= (ReferenceCountedObjectClass* object1, ReferenceCountedObjectPtr<ReferenceCountedObjectClass>& object2) noexcept
 347 {
 348     return object1 != object2.getObject();
 349 }
 350
 351
 352 #endif   // __JUCE_REFERENCECOUNTEDOBJECT_JUCEHEADER__