1// Copyright 2013 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// Provides a smart pointer class for intrusively reference-counted objects.
6
7#ifndef FLUTTER_FML_MEMORY_REF_PTR_H_
8#define FLUTTER_FML_MEMORY_REF_PTR_H_
9
10#include <cstddef>
11#include <functional>
12#include <utility>
13
14#include "flutter/fml/logging.h"
15#include "flutter/fml/macros.h"
16#include "flutter/fml/memory/ref_ptr_internal.h"
17
18namespace fml {
19
20// A smart pointer class for intrusively reference-counted objects (e.g., those
21// subclassing |RefCountedThreadSafe| -- see ref_counted.h).
22//
23// Such objects require *adoption* to obtain the first |RefPtr|, which is
24// accomplished using |AdoptRef| (see below). (This is due to such objects being
25// constructed with a reference count of 1. The adoption requirement is
26// enforced, at least in Debug builds, by assertions.)
27//
28// E.g., if |Foo| is an intrusively reference-counted class:
29//
30// // The |AdoptRef| may be put in a static factory method (e.g., if |Foo|'s
31// // constructor is private).
32// RefPtr<Foo> my_foo_ptr(AdoptRef(new Foo()));
33//
34// // Now OK, since "my Foo" has been adopted ...
35// RefPtr<Foo> another_ptr_to_my_foo(my_foo_ptr.get());
36//
37// // ... though this would preferable in this situation.
38// RefPtr<Foo> yet_another_ptr_to_my_foo(my_foo_ptr);
39//
40// Unlike Chromium's |scoped_refptr|, |RefPtr| is only explicitly constructible
41// from a plain pointer (and not assignable). It is however implicitly
42// constructible from |nullptr|. So:
43//
44// RefPtr<Foo> foo(plain_ptr_to_adopted_foo); // OK.
45// foo = plain_ptr_to_adopted_foo; // Not OK (doesn't compile).
46// foo = RefPtr<Foo>(plain_ptr_to_adopted_foo); // OK.
47// foo = nullptr; // OK.
48//
49// And if we have |void MyFunction(RefPtr<Foo> foo)|, calling it using
50// |MyFunction(nullptr)| is also valid.
51//
52// Implementation note: For copy/move constructors/operator=s, we often have
53// templated versions, so that the operation can be done on a |RefPtr<U>|, where
54// |U| is a subclass of |T|. However, we also have non-templated versions with
55// |U = T|, since the templated versions don't count as copy/move
56// constructors/operator=s for the purposes of causing the default copy
57// constructor/operator= to be deleted. E.g., if we didn't declare any
58// non-templated versions, we'd get the default copy constructor/operator= (we'd
59// only not get the default move constructor/operator= by virtue of having a
60// destructor)! (In fact, it'd suffice to only declare a non-templated move
61// constructor or move operator=, which would cause the copy
62// constructor/operator= to be deleted, but for clarity we include explicit
63// non-templated versions of everything.)
64template <typename T>
65class RefPtr final {
66 public:
67 RefPtr() : ptr_(nullptr) {}
68 RefPtr(std::nullptr_t) // NOLINT(google-explicit-constructor)
69 : ptr_(nullptr) {}
70
71 // Explicit constructor from a plain pointer (to an object that must have
72 // already been adopted). (Note that in |T::T()|, references to |this| cannot
73 // be taken, since the object being constructed will not have been adopted
74 // yet.)
75 template <typename U>
76 explicit RefPtr(U* p) : ptr_(p) {
77 if (ptr_) {
78 ptr_->AddRef();
79 }
80 }
81
82 // Copy constructor.
83 RefPtr(const RefPtr<T>& r) // NOLINT(google-explicit-constructor)
84 : ptr_(r.ptr_) {
85 if (ptr_) {
86 ptr_->AddRef();
87 }
88 }
89
90 template <typename U>
91 RefPtr(const RefPtr<U>& r) // NOLINT(google-explicit-constructor)
92 : ptr_(r.ptr_) {
93 if (ptr_) {
94 ptr_->AddRef();
95 }
96 }
97
98 // Move constructor.
99 RefPtr(RefPtr<T>&& r) : ptr_(r.ptr_) { // NOLINT(google-explicit-constructor)
100 r.ptr_ = nullptr;
101 }
102
103 template <typename U>
104 RefPtr(RefPtr<U>&& r) : ptr_(r.ptr_) { // NOLINT(google-explicit-constructor)
105 r.ptr_ = nullptr;
106 }
107
108 // Destructor.
109 ~RefPtr() {
110 if (ptr_) {
111 ptr_->Release();
112 }
113 }
114
115 T* get() const { return ptr_; }
116
117 T& operator*() const {
118 FML_DCHECK(ptr_);
119 return *ptr_;
120 }
121
122 T* operator->() const {
123 FML_DCHECK(ptr_);
124 return ptr_;
125 }
126
127 // Copy assignment.
128 RefPtr<T>& operator=(const RefPtr<T>& r) {
129 // Handle self-assignment.
130 if (r.ptr_ == ptr_) {
131 return *this;
132 }
133 if (r.ptr_) {
134 r.ptr_->AddRef();
135 }
136 T* old_ptr = ptr_;
137 ptr_ = r.ptr_;
138 if (old_ptr) {
139 old_ptr->Release();
140 }
141 return *this;
142 }
143
144 template <typename U>
145 RefPtr<T>& operator=(const RefPtr<U>& r) {
146 if (reinterpret_cast<T*>(r.ptr_) == ptr_) {
147 return *this;
148 }
149 if (r.ptr_) {
150 r.ptr_->AddRef();
151 }
152 T* old_ptr = ptr_;
153 ptr_ = r.ptr_;
154 if (old_ptr) {
155 old_ptr->Release();
156 }
157 return *this;
158 }
159
160 // Move assignment.
161 // Note: Like |std::shared_ptr|, we support self-move and move assignment is
162 // equivalent to |RefPtr<T>(std::move(r)).swap(*this)|.
163 RefPtr<T>& operator=(RefPtr<T>&& r) {
164 RefPtr<T>(std::move(r)).swap(*this);
165 return *this;
166 }
167
168 template <typename U>
169 RefPtr<T>& operator=(RefPtr<U>&& r) {
170 RefPtr<T>(std::move(r)).swap(*this);
171 return *this;
172 }
173
174 void swap(RefPtr<T>& r) {
175 T* p = ptr_;
176 ptr_ = r.ptr_;
177 r.ptr_ = p;
178 }
179
180 // Returns a new |RefPtr<T>| with the same contents as this pointer. Useful
181 // when a function takes a |RefPtr<T>&&| argument and the caller wants to
182 // retain its reference (rather than moving it).
183 RefPtr<T> Clone() const { return *this; }
184
185 explicit operator bool() const { return !!ptr_; }
186
187 template <typename U>
188 bool operator==(const RefPtr<U>& rhs) const {
189 return ptr_ == rhs.ptr_;
190 }
191
192 template <typename U>
193 bool operator!=(const RefPtr<U>& rhs) const {
194 return !operator==(rhs);
195 }
196
197 template <typename U>
198 bool operator<(const RefPtr<U>& rhs) const {
199 return ptr_ < rhs.ptr_;
200 }
201
202 private:
203 template <typename U>
204 friend class RefPtr;
205
206 friend RefPtr<T> AdoptRef<T>(T*);
207
208 enum AdoptTag { ADOPT };
209 RefPtr(T* ptr, AdoptTag) : ptr_(ptr) { FML_DCHECK(ptr_); }
210
211 T* ptr_;
212};
213
214// Adopts a newly-created |T|. Typically used in a static factory method, like:
215//
216// // static
217// RefPtr<Foo> Foo::Create() {
218// return AdoptRef(new Foo());
219// }
220template <typename T>
221inline RefPtr<T> AdoptRef(T* ptr) {
222#ifndef NDEBUG
223 ptr->Adopt();
224#endif
225 return RefPtr<T>(ptr, RefPtr<T>::ADOPT);
226}
227
228// Constructs a |RefPtr<T>| from a plain pointer (to an object that must
229// have already been adoped). Avoids having to spell out the full type name.
230//
231// Foo* foo = ...;
232// auto foo_ref = Ref(foo);
233//
234// (|foo_ref| will be of type |RefPtr<Foo>|.)
235template <typename T>
236inline RefPtr<T> Ref(T* ptr) {
237 return RefPtr<T>(ptr);
238}
239
240// Creates an intrusively reference counted |T|, producing a |RefPtr<T>| (and
241// performing the required adoption). Use like:
242//
243// auto my_foo = MakeRefCounted<Foo>(ctor_arg1, ctor_arg2);
244//
245// (|my_foo| will be of type |RefPtr<Foo>|.)
246template <typename T, typename... Args>
247RefPtr<T> MakeRefCounted(Args&&... args) {
248 return internal::MakeRefCountedHelper<T>::MakeRefCounted(
249 std::forward<Args>(args)...);
250}
251
252} // namespace fml
253
254// Inject custom std::hash<> function object for |RefPtr<T>|.
255namespace std {
256template <typename T>
257struct hash<fml::RefPtr<T>> {
258 using argument_type = fml::RefPtr<T>;
259 using result_type = std::size_t;
260
261 result_type operator()(const argument_type& ptr) const {
262 return std::hash<T*>()(ptr.get());
263 }
264};
265} // namespace std
266
267#endif // FLUTTER_FML_MEMORY_REF_PTR_H_
268

source code of flutter_engine/flutter/fml/memory/ref_ptr.h