mfbt/RefPtr.h

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