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/. */
6 /* Helpers for defining and using refcounted objects. */
8 #ifndef mozilla_RefPtr_h_
9 #define mozilla_RefPtr_h_
11 #include "mozilla/Assertions.h"
12 #include "mozilla/Attributes.h"
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
>&);
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
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.
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==-0xdead. This
40 * state distinguishes use-before-ref (refcount==0) from
41 * use-after-destroy (refcount==-0xdead).
46 friend class RefPtr
<T
>;
49 RefCounted() : refCnt(0) { }
50 ~RefCounted() { MOZ_ASSERT(refCnt
== -0xdead); }
52 // Compatibility with nsRefPtr.
54 MOZ_ASSERT(refCnt
>= 0);
59 MOZ_ASSERT(refCnt
> 0);
64 delete static_cast<T
*>(this);
68 // Compatibility with wtf::RefPtr.
69 void ref() { AddRef(); }
70 void deref() { Release(); }
71 int refCount() const { return refCnt
; }
72 bool hasOneRef() const {
73 MOZ_ASSERT(refCnt
> 0);
82 * RefPtr points to a refcounted thing that has AddRef and Release
83 * methods to increase/decrease the refcount, respectively. After a
84 * RefPtr<T> is assigned a T*, the T* can be used through the RefPtr
87 * A RefPtr can forget its underlying T*, which results in the T*
88 * being wrapped in a temporary object until the T* is either
89 * re-adopted from or released by the temporary.
94 // To allow them to use unref()
95 friend class TemporaryRef
<T
>;
96 friend class OutParamRef
<T
>;
101 RefPtr() : ptr(0) { }
102 RefPtr(const RefPtr
& o
) : ptr(ref(o
.ptr
)) {}
103 RefPtr(const TemporaryRef
<T
>& o
) : ptr(o
.drop()) {}
104 RefPtr(T
* t
) : ptr(ref(t
)) {}
107 RefPtr(const RefPtr
<U
>& o
) : ptr(ref(o
.get())) {}
109 ~RefPtr() { unref(ptr
); }
111 RefPtr
& operator=(const RefPtr
& o
) {
115 RefPtr
& operator=(const TemporaryRef
<T
>& o
) {
119 RefPtr
& operator=(T
* t
) {
125 RefPtr
& operator=(const RefPtr
<U
>& o
) {
126 assign(ref(o
.get()));
130 TemporaryRef
<T
> forget() {
133 return TemporaryRef
<T
>(tmp
, DontRef());
136 T
* get() const { return ptr
; }
137 operator T
*() const { return ptr
; }
138 T
* operator->() const { return ptr
; }
139 T
& operator*() const { return *ptr
; }
141 operator TemporaryRef
<U
>() { return TemporaryRef
<U
>(ptr
); }
151 static MOZ_ALWAYS_INLINE T
* ref(T
* t
) {
157 static MOZ_ALWAYS_INLINE
void unref(T
* t
) {
164 * TemporaryRef<T> represents an object that holds a temporary
165 * reference to a T. TemporaryRef objects can't be manually ref'd or
166 * unref'd (being temporaries, not lvalues), so can only relinquish
167 * references to other objects, or unref on destruction.
172 // To allow it to construct TemporaryRef from a bare T*
173 friend class RefPtr
<T
>;
175 typedef typename RefPtr
<T
>::DontRef DontRef
;
178 TemporaryRef(T
* t
) : ptr(RefPtr
<T
>::ref(t
)) {}
179 TemporaryRef(const TemporaryRef
& o
) : ptr(o
.drop()) {}
182 TemporaryRef(const TemporaryRef
<U
>& o
) : ptr(o
.drop()) {}
184 ~TemporaryRef() { RefPtr
<T
>::unref(ptr
); }
193 TemporaryRef(T
* t
, const DontRef
&) : ptr(t
) {}
197 TemporaryRef() MOZ_DELETE
;
198 void operator=(const TemporaryRef
&) MOZ_DELETE
;
202 * OutParamRef is a wrapper that tracks a refcounted pointer passed as
203 * an outparam argument to a function. OutParamRef implements COM T**
204 * outparam semantics: this requires the callee to AddRef() the T*
205 * returned through the T** outparam on behalf of the caller. This
206 * means the caller (through OutParamRef) must Release() the old
207 * object contained in the tracked RefPtr. It's OK if the callee
208 * returns the same T* passed to it through the T** outparam, as long
209 * as the callee obeys the COM discipline.
211 * Prefer returning TemporaryRef<T> from functions over creating T**
212 * outparams and passing OutParamRef<T> to T**. Prefer RefPtr<T>*
213 * outparams over T** outparams.
218 friend OutParamRef byRef
<T
>(RefPtr
<T
>&);
222 RefPtr
<T
>::unref(refPtr
.ptr
);
226 operator T
**() { return &tmp
; }
229 OutParamRef(RefPtr
<T
>& p
) : refPtr(p
), tmp(p
.get()) {}
234 OutParamRef() MOZ_DELETE
;
235 OutParamRef
& operator=(const OutParamRef
&) MOZ_DELETE
;
239 * byRef cooperates with OutParamRef to implement COM outparam semantics.
243 byRef(RefPtr
<T
>& ptr
)
245 return OutParamRef
<T
>(ptr
);
248 } // namespace mozilla
250 #endif // mozilla_RefPtr_h_
255 // Command line that builds these tests
257 // cp RefPtr.h test.cc && g++ -g -Wall -pedantic -DDEBUG -o test test.cc && ./test
259 using namespace mozilla
;
261 struct Foo
: public RefCounted
<Foo
>
263 Foo() : dead(false) { }
271 static int numDestroyed
;
273 int Foo::numDestroyed
;
275 struct Bar
: public Foo
{ };
280 return RefPtr
<Foo
>(new Foo());
293 // Kids, don't try this at home
298 GetPassedFoo(Foo
** f
)
300 // Kids, don't try this at home
305 GetNewFoo(RefPtr
<Foo
>* f
)
311 GetPassedFoo(RefPtr
<Foo
>* f
)
321 main(int argc
, char** argv
)
323 // This should blow up
324 // Foo* f = new Foo(); delete f;
326 MOZ_ASSERT(0 == Foo::numDestroyed
);
328 RefPtr
<Foo
> f
= new Foo();
329 MOZ_ASSERT(f
->refCount() == 1);
331 MOZ_ASSERT(1 == Foo::numDestroyed
);
334 RefPtr
<Foo
> f1
= NewFoo();
335 RefPtr
<Foo
> f2(NewFoo());
336 MOZ_ASSERT(1 == Foo::numDestroyed
);
338 MOZ_ASSERT(3 == Foo::numDestroyed
);
341 RefPtr
<Foo
> b
= NewBar();
342 MOZ_ASSERT(3 == Foo::numDestroyed
);
344 MOZ_ASSERT(4 == Foo::numDestroyed
);
352 MOZ_ASSERT(4 == Foo::numDestroyed
);
354 MOZ_ASSERT(4 == Foo::numDestroyed
);
356 MOZ_ASSERT(5 == Foo::numDestroyed
);
359 RefPtr
<Foo
> f
= new Foo();
361 MOZ_ASSERT(6 == Foo::numDestroyed
);
365 RefPtr
<Foo
> f
= new Foo();
367 MOZ_ASSERT(7 == Foo::numDestroyed
);
369 MOZ_ASSERT(8 == Foo::numDestroyed
);
372 RefPtr
<Foo
> f
= new Foo();
373 GetPassedFoo(byRef(f
));
374 MOZ_ASSERT(8 == Foo::numDestroyed
);
376 MOZ_ASSERT(9 == Foo::numDestroyed
);
379 RefPtr
<Foo
> f
= new Foo();
381 MOZ_ASSERT(10 == Foo::numDestroyed
);
383 MOZ_ASSERT(11 == Foo::numDestroyed
);
386 RefPtr
<Foo
> f
= new Foo();
388 MOZ_ASSERT(11 == Foo::numDestroyed
);
390 MOZ_ASSERT(12 == Foo::numDestroyed
);
393 RefPtr
<Foo
> f1
= new Bar();
395 MOZ_ASSERT(13 == Foo::numDestroyed
);
398 RefPtr
<Foo
> f
= GetNullFoo();
399 MOZ_ASSERT(13 == Foo::numDestroyed
);
401 MOZ_ASSERT(13 == Foo::numDestroyed
);