1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 /* Typed temporary pointers for reference-counted smart pointers. */
9 #ifndef AlreadyAddRefed_h
10 #define AlreadyAddRefed_h
12 #include "mozilla/Assertions.h"
13 #include "mozilla/Attributes.h"
14 #include "mozilla/Move.h"
20 } // namespace mozilla
23 * already_AddRefed cooperates with reference counting smart pointers to enable
24 * you to assign in a pointer _without_ |AddRef|ing it. You might want to use
25 * this as a return type from a function that returns an already |AddRef|ed
28 * TODO Move already_AddRefed to namespace mozilla. This has not yet been done
29 * because of the sheer number of usages of already_AddRefed.
31 * When should you use already_AddRefed<>?
32 * * Ensure a consumer takes ownership of a reference
33 * * Pass ownership without calling AddRef/Release (sometimes required in
34 * off-main-thread code)
35 * * The ref pointer type you're using doesn't support move construction
37 * Otherwise, use std::move(RefPtr/nsCOMPtr/etc).
40 struct MOZ_MUST_USE_TYPE MOZ_NON_AUTOABLE already_AddRefed
{
41 already_AddRefed() : mRawPtr(nullptr) {}
43 // For simplicity, allow returning nullptr from functions returning
44 // already_AddRefed<T>. Don't permit returning raw T*, though; it's preferred
45 // to create already_AddRefed<T> from a reference-counting smart pointer.
46 MOZ_IMPLICIT
already_AddRefed(decltype(nullptr)) : mRawPtr(nullptr) {}
47 explicit already_AddRefed(T
* aRawPtr
) : mRawPtr(aRawPtr
) {}
49 // Disallow copy constructor and copy assignment operator: move semantics used
51 already_AddRefed(const already_AddRefed
<T
>& aOther
) = delete;
52 already_AddRefed
<T
>& operator=(const already_AddRefed
<T
>& aOther
) = delete;
54 // WARNING: sketchiness ahead.
56 // The x86-64 ABI for Unix-like operating systems requires structures to be
57 // returned via invisible reference if they are non-trivial for the purposes
58 // of calls according to the C++ ABI[1]. For our consideration here, that
59 // means that if we have a non-trivial move constructor or destructor,
60 // already_AddRefed must be returned by invisible reference. But
61 // already_AddRefed is small enough and so commonly used that it would be
62 // beneficial to return it via registers instead. So we need to figure out
63 // a way to make the move constructor and the destructor trivial.
65 // Our destructor is normally non-trivial, because it asserts that the
66 // stored pointer has been taken by somebody else prior to destruction.
67 // However, since the assert in question is compiled only for DEBUG builds,
68 // we can make the destructor trivial in non-DEBUG builds by simply defining
69 // it with `= default`.
71 // We now have to make the move constructor trivial as well. It is normally
72 // non-trivial, because the incoming object has its pointer null-ed during
73 // the move. This null-ing is done to satisfy the assert in the destructor.
74 // But since that destructor has no assert in non-DEBUG builds, the clearing
75 // is unnecessary in such builds; all we really need to perform is a copy of
76 // the pointer from the incoming object. So we can let the compiler define
77 // a trivial move constructor for us, and already_AddRefed can now be
78 // returned in registers rather than needing to allocate a stack slot for
79 // an invisible reference.
81 // The above considerations apply to Unix-like operating systems only; the
82 // conditions for the same optimization to apply on x86-64 Windows are much
83 // more strigent and are basically impossible for already_AddRefed to
84 // satisfy[2]. But we do get some benefit from this optimization on Windows
85 // because we removed the nulling of the pointer during the move, so that's
88 // [1] https://itanium-cxx-abi.github.io/cxx-abi/abi.html#non-trivial
89 // [2] https://docs.microsoft.com/en-us/cpp/build/return-values-cpp
91 already_AddRefed(already_AddRefed
<T
>&& aOther
)
93 : mRawPtr(aOther
.take()) {
99 already_AddRefed
<T
>& operator=(already_AddRefed
<T
>&& aOther
) {
100 mRawPtr
= aOther
.take();
105 * This helper is useful in cases like
107 * already_AddRefed<BaseClass>
110 * RefPtr<SubClass> x = ...;
114 * The autoconversion allows one to omit the idiom
116 * RefPtr<BaseClass> y = x.forget();
119 * Note that nsRefPtr is the XPCOM reference counting smart pointer class.
121 template <typename U
>
122 MOZ_IMPLICIT
already_AddRefed(already_AddRefed
<U
>&& aOther
)
123 : mRawPtr(aOther
.take()) {}
128 MOZ_ASSERT(!mRawPtr
);
134 // Specialize the unused operator<< for already_AddRefed, to allow
135 // nsCOMPtr<nsIFoo> foo;
136 // Unused << foo.forget();
137 // Note that nsCOMPtr is the XPCOM reference counting smart pointer class.
138 friend void operator<<(const mozilla::unused_t
& aUnused
,
139 const already_AddRefed
<T
>& aRhs
) {
140 auto mutableAlreadyAddRefed
= const_cast<already_AddRefed
<T
>*>(&aRhs
);
141 aUnused
<< mutableAlreadyAddRefed
->take();
144 MOZ_MUST_USE T
* take() {
151 * This helper provides a static_cast replacement for already_AddRefed, so
154 * already_AddRefed<Parent> F();
158 * already_AddRefed<Child>
161 * return F().downcast<Child>();
165 already_AddRefed
<U
> downcast() {
166 U
* tmp
= static_cast<U
*>(mRawPtr
);
168 return already_AddRefed
<U
>(tmp
);
172 T
* MOZ_OWNING_REF mRawPtr
;
175 #endif // AlreadyAddRefed_h