mfbt/RefPtr.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /* Helpers for defining and using refcounted objects. */
   7
   8 #ifndef mozilla_RefPtr_h_
   9 #define mozilla_RefPtr_h_
  10
  11 #include "mozilla/Assertions.h"
  12 #include "mozilla/Attributes.h"
  13
  14 namespace mozilla {
  15
  16 template<typename T> class RefCounted;
  17 template<typename T> class RefPtr;
  18 template<typename T> class TemporaryRef;
  19 template<typename T> class OutParamRef;
  20 template<typename T> OutParamRef<T> byRef(RefPtr<T>&);
  21
  22 /**
  23  * RefCounted<T> is a sort of a "mixin" for a class T.  RefCounted
  24  * manages, well, refcounting for T, and because RefCounted is
  25  * parameterized on T, RefCounted<T> can call T's destructor directly.
  26  * This means T doesn't need to have a virtual dtor and so doesn't
  27  * need a vtable.
  28  *
  29  * RefCounted<T> is created with refcount == 0.  Newly-allocated
  30  * RefCounted<T> must immediately be assigned to a RefPtr to make the
  31  * refcount > 0.  It's an error to allocate and free a bare
  32  * RefCounted<T>, i.e. outside of the RefPtr machinery.  Attempts to
  33  * do so will abort DEBUG builds.
  34  *
  35  * Live RefCounted<T> have refcount > 0.  The lifetime (refcounts) of
  36  * live RefCounted<T> are controlled by RefPtr<T> and
  37  * RefPtr<super/subclass of T>.  Upon a transition from refcounted==1
  38  * to 0, the RefCounted<T> "dies" and is destroyed.  The "destroyed"
  39  * state is represented in DEBUG builds by refcount==0xffffdead.  This
  40  * state distinguishes use-before-ref (refcount==0) from
  41  * use-after-destroy (refcount==0xffffdead).
  42  */
  43 #ifdef DEBUG
  44 namespace detail {
  45 static const int DEAD = 0xffffdead;
  46 }
  47 #endif
  48
  49 template<typename T>
  50 class RefCounted
  51 {
  52     friend class RefPtr<T>;
  53
  54   protected:
  55     RefCounted() : refCnt(0) { }
  56     ~RefCounted() { MOZ_ASSERT(refCnt == detail::DEAD); }
  57
  58   public:
  59     // Compatibility with nsRefPtr.
  60     void AddRef() {
  61       MOZ_ASSERT(refCnt >= 0);
  62       ++refCnt;
  63     }
  64
  65     void Release() {
  66       MOZ_ASSERT(refCnt > 0);
  67       if (0 == --refCnt) {
  68 #ifdef DEBUG
  69         refCnt = detail::DEAD;
  70 #endif
  71         delete static_cast<T*>(this);
  72       }
  73     }
  74
  75     // Compatibility with wtf::RefPtr.
  76     void ref() { AddRef(); }
  77     void deref() { Release(); }
  78     int refCount() const { return refCnt; }
  79     bool hasOneRef() const {
  80       MOZ_ASSERT(refCnt > 0);
  81       return refCnt == 1;
  82     }
  83
  84   private:
  85     int refCnt;
  86 };
  87
  88 /**
  89  * RefPtr points to a refcounted thing that has AddRef and Release
  90  * methods to increase/decrease the refcount, respectively.  After a
  91  * RefPtr<T> is assigned a T*, the T* can be used through the RefPtr
  92  * as if it were a T*.
  93  *
  94  * A RefPtr can forget its underlying T*, which results in the T*
  95  * being wrapped in a temporary object until the T* is either
  96  * re-adopted from or released by the temporary.
  97  */
  98 template<typename T>
  99 class RefPtr
 100 {
 101     // To allow them to use unref()
 102     friend class TemporaryRef<T>;
 103     friend class OutParamRef<T>;
 104
 105     struct DontRef {};
 106
 107   public:
 108     RefPtr() : ptr(0) { }
 109     RefPtr(const RefPtr& o) : ptr(ref(o.ptr)) {}
 110     RefPtr(const TemporaryRef<T>& o) : ptr(o.drop()) {}
 111     RefPtr(T* t) : ptr(ref(t)) {}
 112
 113     template<typename U>
 114     RefPtr(const RefPtr<U>& o) : ptr(ref(o.get())) {}
 115
 116     ~RefPtr() { unref(ptr); }
 117
 118     RefPtr& operator=(const RefPtr& o) {
 119       assign(ref(o.ptr));
 120       return *this;
 121     }
 122     RefPtr& operator=(const TemporaryRef<T>& o) {
 123       assign(o.drop());
 124       return *this;
 125     }
 126     RefPtr& operator=(T* t) {
 127       assign(ref(t));
 128       return *this;
 129     }
 130
 131     template<typename U>
 132     RefPtr& operator=(const RefPtr<U>& o) {
 133       assign(ref(o.get()));
 134       return *this;
 135     }
 136
 137     TemporaryRef<T> forget() {
 138       T* tmp = ptr;
 139       ptr = 0;
 140       return TemporaryRef<T>(tmp, DontRef());
 141     }
 142
 143     T* get() const { return ptr; }
 144     operator T*() const { return ptr; }
 145     T* operator->() const { return ptr; }
 146     T& operator*() const { return *ptr; }
 147     template<typename U>
 148     operator TemporaryRef<U>() { return TemporaryRef<U>(ptr); }
 149
 150   private:
 151     void assign(T* t) {
 152       unref(ptr);
 153       ptr = t;
 154     }
 155
 156     T* ptr;
 157
 158     static MOZ_ALWAYS_INLINE T* ref(T* t) {
 159       if (t)
 160         t->AddRef();
 161       return t;
 162     }
 163
 164     static MOZ_ALWAYS_INLINE void unref(T* t) {
 165       if (t)
 166         t->Release();
 167     }
 168 };
 169
 170 /**
 171  * TemporaryRef<T> represents an object that holds a temporary
 172  * reference to a T.  TemporaryRef objects can't be manually ref'd or
 173  * unref'd (being temporaries, not lvalues), so can only relinquish
 174  * references to other objects, or unref on destruction.
 175  */
 176 template<typename T>
 177 class TemporaryRef
 178 {
 179     // To allow it to construct TemporaryRef from a bare T*
 180     friend class RefPtr<T>;
 181
 182     typedef typename RefPtr<T>::DontRef DontRef;
 183
 184   public:
 185     TemporaryRef(T* t) : ptr(RefPtr<T>::ref(t)) {}
 186     TemporaryRef(const TemporaryRef& o) : ptr(o.drop()) {}
 187
 188     template<typename U>
 189     TemporaryRef(const TemporaryRef<U>& o) : ptr(o.drop()) {}
 190
 191     ~TemporaryRef() { RefPtr<T>::unref(ptr); }
 192
 193     T* drop() const {
 194       T* tmp = ptr;
 195       ptr = 0;
 196       return tmp;
 197     }
 198
 199   private:
 200     TemporaryRef(T* t, const DontRef&) : ptr(t) {}
 201
 202     mutable T* ptr;
 203
 204     TemporaryRef() MOZ_DELETE;
 205     void operator=(const TemporaryRef&) MOZ_DELETE;
 206 };
 207
 208 /**
 209  * OutParamRef is a wrapper that tracks a refcounted pointer passed as
 210  * an outparam argument to a function.  OutParamRef implements COM T**
 211  * outparam semantics: this requires the callee to AddRef() the T*
 212  * returned through the T** outparam on behalf of the caller.  This
 213  * means the caller (through OutParamRef) must Release() the old
 214  * object contained in the tracked RefPtr.  It's OK if the callee
 215  * returns the same T* passed to it through the T** outparam, as long
 216  * as the callee obeys the COM discipline.
 217  *
 218  * Prefer returning TemporaryRef<T> from functions over creating T**
 219  * outparams and passing OutParamRef<T> to T**.  Prefer RefPtr<T>*
 220  * outparams over T** outparams.
 221  */
 222 template<typename T>
 223 class OutParamRef
 224 {
 225     friend OutParamRef byRef<T>(RefPtr<T>&);
 226
 227   public:
 228     ~OutParamRef() {
 229       RefPtr<T>::unref(refPtr.ptr);
 230       refPtr.ptr = tmp;
 231     }
 232
 233     operator T**() { return &tmp; }
 234
 235   private:
 236     OutParamRef(RefPtr<T>& p) : refPtr(p), tmp(p.get()) {}
 237
 238     RefPtr<T>& refPtr;
 239     T* tmp;
 240
 241     OutParamRef() MOZ_DELETE;
 242     OutParamRef& operator=(const OutParamRef&) MOZ_DELETE;
 243 };
 244
 245 /**
 246  * byRef cooperates with OutParamRef to implement COM outparam semantics.
 247  */
 248 template<typename T>
 249 OutParamRef<T>
 250 byRef(RefPtr<T>& ptr)
 251 {
 252   return OutParamRef<T>(ptr);
 253 }
 254
 255 } // namespace mozilla
 256
 257 #endif // mozilla_RefPtr_h_
 258
 259
 260 #if 0
 261
 262 // Command line that builds these tests
 263 //
 264 //   cp RefPtr.h test.cc && g++ -g -Wall -pedantic -DDEBUG -o test test.cc && ./test
 265
 266 using namespace mozilla;
 267
 268 struct Foo : public RefCounted<Foo>
 269 {
 270   Foo() : dead(false) { }
 271   ~Foo() {
 272     MOZ_ASSERT(!dead);
 273     dead = true;
 274     numDestroyed++;
 275   }
 276
 277   bool dead;
 278   static int numDestroyed;
 279 };
 280 int Foo::numDestroyed;
 281
 282 struct Bar : public Foo { };
 283
 284 TemporaryRef<Foo>
 285 NewFoo()
 286 {
 287   return RefPtr<Foo>(new Foo());
 288 }
 289
 290 TemporaryRef<Foo>
 291 NewBar()
 292 {
 293   return new Bar();
 294 }
 295
 296 void
 297 GetNewFoo(Foo** f)
 298 {
 299   *f = new Bar();
 300   // Kids, don't try this at home
 301   (*f)->AddRef();
 302 }
 303
 304 void
 305 GetPassedFoo(Foo** f)
 306 {
 307   // Kids, don't try this at home
 308   (*f)->AddRef();
 309 }
 310
 311 void
 312 GetNewFoo(RefPtr<Foo>* f)
 313 {
 314   *f = new Bar();
 315 }
 316
 317 void
 318 GetPassedFoo(RefPtr<Foo>* f)
 319 {}
 320
 321 TemporaryRef<Foo>
 322 GetNullFoo()
 323 {
 324   return 0;
 325 }
 326
 327 int
 328 main(int argc, char** argv)
 329 {
 330   // This should blow up
 331 //    Foo* f = new Foo(); delete f;
 332
 333   MOZ_ASSERT(0 == Foo::numDestroyed);
 334   {
 335     RefPtr<Foo> f = new Foo();
 336     MOZ_ASSERT(f->refCount() == 1);
 337   }
 338   MOZ_ASSERT(1 == Foo::numDestroyed);
 339
 340   {
 341     RefPtr<Foo> f1 = NewFoo();
 342     RefPtr<Foo> f2(NewFoo());
 343     MOZ_ASSERT(1 == Foo::numDestroyed);
 344   }
 345   MOZ_ASSERT(3 == Foo::numDestroyed);
 346
 347   {
 348     RefPtr<Foo> b = NewBar();
 349     MOZ_ASSERT(3 == Foo::numDestroyed);
 350   }
 351   MOZ_ASSERT(4 == Foo::numDestroyed);
 352
 353   {
 354     RefPtr<Foo> f1;
 355     {
 356       f1 = new Foo();
 357       RefPtr<Foo> f2(f1);
 358       RefPtr<Foo> f3 = f2;
 359       MOZ_ASSERT(4 == Foo::numDestroyed);
 360     }
 361     MOZ_ASSERT(4 == Foo::numDestroyed);
 362   }
 363   MOZ_ASSERT(5 == Foo::numDestroyed);
 364
 365   {
 366     RefPtr<Foo> f = new Foo();
 367     f.forget();
 368     MOZ_ASSERT(6 == Foo::numDestroyed);
 369   }
 370
 371   {
 372     RefPtr<Foo> f = new Foo();
 373     GetNewFoo(byRef(f));
 374     MOZ_ASSERT(7 == Foo::numDestroyed);
 375   }
 376   MOZ_ASSERT(8 == Foo::numDestroyed);
 377
 378   {
 379     RefPtr<Foo> f = new Foo();
 380     GetPassedFoo(byRef(f));
 381     MOZ_ASSERT(8 == Foo::numDestroyed);
 382   }
 383   MOZ_ASSERT(9 == Foo::numDestroyed);
 384
 385   {
 386     RefPtr<Foo> f = new Foo();
 387     GetNewFoo(&f);
 388     MOZ_ASSERT(10 == Foo::numDestroyed);
 389   }
 390   MOZ_ASSERT(11 == Foo::numDestroyed);
 391
 392   {
 393     RefPtr<Foo> f = new Foo();
 394     GetPassedFoo(&f);
 395     MOZ_ASSERT(11 == Foo::numDestroyed);
 396   }
 397   MOZ_ASSERT(12 == Foo::numDestroyed);
 398
 399   {
 400     RefPtr<Foo> f1 = new Bar();
 401   }
 402   MOZ_ASSERT(13 == Foo::numDestroyed);
 403
 404   {
 405     RefPtr<Foo> f = GetNullFoo();
 406     MOZ_ASSERT(13 == Foo::numDestroyed);
 407   }
 408   MOZ_ASSERT(13 == Foo::numDestroyed);
 409
 410   return 0;
 411 }
 412
 413 #endif