1//==- llvm/ADT/IntrusiveRefCntPtr.h - Smart Refcounting Pointer --*- C++ -*-==//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file defines the RefCountedBase, ThreadSafeRefCountedBase, and
10// IntrusiveRefCntPtr classes.
11//
12// IntrusiveRefCntPtr is a smart pointer to an object which maintains a
13// reference count. (ThreadSafe)RefCountedBase is a mixin class that adds a
14// refcount member variable and methods for updating the refcount. An object
15// that inherits from (ThreadSafe)RefCountedBase deletes itself when its
16// refcount hits zero.
17//
18// For example:
19//
20// class MyClass : public RefCountedBase<MyClass> {};
21//
22// void foo() {
23// // Constructing an IntrusiveRefCntPtr increases the pointee's refcount by
24// // 1 (from 0 in this case).
25// IntrusiveRefCntPtr<MyClass> Ptr1(new MyClass());
26//
27// // Copying an IntrusiveRefCntPtr increases the pointee's refcount by 1.
28// IntrusiveRefCntPtr<MyClass> Ptr2(Ptr1);
29//
30// // Constructing an IntrusiveRefCntPtr has no effect on the object's
31// // refcount. After a move, the moved-from pointer is null.
32// IntrusiveRefCntPtr<MyClass> Ptr3(std::move(Ptr1));
33// assert(Ptr1 == nullptr);
34//
35// // Clearing an IntrusiveRefCntPtr decreases the pointee's refcount by 1.
36// Ptr2.reset();
37//
38// // The object deletes itself when we return from the function, because
39// // Ptr3's destructor decrements its refcount to 0.
40// }
41//
42// You can use IntrusiveRefCntPtr with isa<T>(), dyn_cast<T>(), etc.:
43//
44// IntrusiveRefCntPtr<MyClass> Ptr(new MyClass());
45// OtherClass *Other = dyn_cast<OtherClass>(Ptr); // Ptr.get() not required
46//
47// IntrusiveRefCntPtr works with any class that
48//
49// - inherits from (ThreadSafe)RefCountedBase,
50// - has Retain() and Release() methods, or
51// - specializes IntrusiveRefCntPtrInfo.
52//
53//===----------------------------------------------------------------------===//
54
55#ifndef LLVM_ADT_INTRUSIVEREFCNTPTR_H
56#define LLVM_ADT_INTRUSIVEREFCNTPTR_H
57
58#include <atomic>
59#include <cassert>
60#include <cstddef>
61
62namespace llvm {
63
64/// A CRTP mixin class that adds reference counting to a type.
65///
66/// The lifetime of an object which inherits from RefCountedBase is managed by
67/// calls to Release() and Retain(), which increment and decrement the object's
68/// refcount, respectively. When a Release() call decrements the refcount to 0,
69/// the object deletes itself.
70template <class Derived> class RefCountedBase {
71 mutable unsigned RefCount = 0;
72
73public:
74 RefCountedBase() = default;
75 RefCountedBase(const RefCountedBase &) {}
76
77 void Retain() const { ++RefCount; }
78
79 void Release() const {
80 assert(RefCount > 0 && "Reference count is already zero.");
81 if (--RefCount == 0)
82 delete static_cast<const Derived *>(this);
83 }
84};
85
86/// A thread-safe version of \c RefCountedBase.
87template <class Derived> class ThreadSafeRefCountedBase {
88 mutable std::atomic<int> RefCount;
89
90protected:
91 ThreadSafeRefCountedBase() : RefCount(0) {}
92
93public:
94 void Retain() const { RefCount.fetch_add(1, std::memory_order_relaxed); }
95
96 void Release() const {
97 int NewRefCount = RefCount.fetch_sub(1, std::memory_order_acq_rel) - 1;
98 assert(NewRefCount >= 0 && "Reference count was already zero.");
99 if (NewRefCount == 0)
100 delete static_cast<const Derived *>(this);
101 }
102};
103
104/// Class you can specialize to provide custom retain/release functionality for
105/// a type.
106///
107/// Usually specializing this class is not necessary, as IntrusiveRefCntPtr
108/// works with any type which defines Retain() and Release() functions -- you
109/// can define those functions yourself if RefCountedBase doesn't work for you.
110///
111/// One case when you might want to specialize this type is if you have
112/// - Foo.h defines type Foo and includes Bar.h, and
113/// - Bar.h uses IntrusiveRefCntPtr<Foo> in inline functions.
114///
115/// Because Foo.h includes Bar.h, Bar.h can't include Foo.h in order to pull in
116/// the declaration of Foo. Without the declaration of Foo, normally Bar.h
117/// wouldn't be able to use IntrusiveRefCntPtr<Foo>, which wants to call
118/// T::Retain and T::Release.
119///
120/// To resolve this, Bar.h could include a third header, FooFwd.h, which
121/// forward-declares Foo and specializes IntrusiveRefCntPtrInfo<Foo>. Then
122/// Bar.h could use IntrusiveRefCntPtr<Foo>, although it still couldn't call any
123/// functions on Foo itself, because Foo would be an incomplete type.
124template <typename T> struct IntrusiveRefCntPtrInfo {
125 static void retain(T *obj) { obj->Retain(); }
126 static void release(T *obj) { obj->Release(); }
127};
128
129/// A smart pointer to a reference-counted object that inherits from
130/// RefCountedBase or ThreadSafeRefCountedBase.
131///
132/// This class increments its pointee's reference count when it is created, and
133/// decrements its refcount when it's destroyed (or is changed to point to a
134/// different object).
135template <typename T> class IntrusiveRefCntPtr {
136 T *Obj = nullptr;
137
138public:
139 using element_type = T;
140
141 explicit IntrusiveRefCntPtr() = default;
142 IntrusiveRefCntPtr(T *obj) : Obj(obj) { retain(); }
143 IntrusiveRefCntPtr(const IntrusiveRefCntPtr &S) : Obj(S.Obj) { retain(); }
144 IntrusiveRefCntPtr(IntrusiveRefCntPtr &&S) : Obj(S.Obj) { S.Obj = nullptr; }
145
146 template <class X>
147 IntrusiveRefCntPtr(IntrusiveRefCntPtr<X> &&S) : Obj(S.get()) {
148 S.Obj = nullptr;
149 }
150
151 template <class X>
152 IntrusiveRefCntPtr(const IntrusiveRefCntPtr<X> &S) : Obj(S.get()) {
153 retain();
154 }
155
156 ~IntrusiveRefCntPtr() { release(); }
157
158 IntrusiveRefCntPtr &operator=(IntrusiveRefCntPtr S) {
159 swap(S);
160 return *this;
161 }
162
163 T &operator*() const { return *Obj; }
164 T *operator->() const { return Obj; }
165 T *get() const { return Obj; }
166 explicit operator bool() const { return Obj; }
167
168 void swap(IntrusiveRefCntPtr &other) {
169 T *tmp = other.Obj;
170 other.Obj = Obj;
171 Obj = tmp;
172 }
173
174 void reset() {
175 release();
176 Obj = nullptr;
177 }
178
179 void resetWithoutRelease() { Obj = nullptr; }
180
181private:
182 void retain() {
183 if (Obj)
184 IntrusiveRefCntPtrInfo<T>::retain(Obj);
185 }
186
187 void release() {
188 if (Obj)
189 IntrusiveRefCntPtrInfo<T>::release(Obj);
190 }
191
192 template <typename X> friend class IntrusiveRefCntPtr;
193};
194
195template <class T, class U>
196inline bool operator==(const IntrusiveRefCntPtr<T> &A,
197 const IntrusiveRefCntPtr<U> &B) {
198 return A.get() == B.get();
199}
200
201template <class T, class U>
202inline bool operator!=(const IntrusiveRefCntPtr<T> &A,
203 const IntrusiveRefCntPtr<U> &B) {
204 return A.get() != B.get();
205}
206
207template <class T, class U>
208inline bool operator==(const IntrusiveRefCntPtr<T> &A, U *B) {
209 return A.get() == B;
210}
211
212template <class T, class U>
213inline bool operator!=(const IntrusiveRefCntPtr<T> &A, U *B) {
214 return A.get() != B;
215}
216
217template <class T, class U>
218inline bool operator==(T *A, const IntrusiveRefCntPtr<U> &B) {
219 return A == B.get();
220}
221
222template <class T, class U>
223inline bool operator!=(T *A, const IntrusiveRefCntPtr<U> &B) {
224 return A != B.get();
225}
226
227template <class T>
228bool operator==(std::nullptr_t A, const IntrusiveRefCntPtr<T> &B) {
229 return !B;
230}
231
232template <class T>
233bool operator==(const IntrusiveRefCntPtr<T> &A, std::nullptr_t B) {
234 return B == A;
235}
236
237template <class T>
238bool operator!=(std::nullptr_t A, const IntrusiveRefCntPtr<T> &B) {
239 return !(A == B);
240}
241
242template <class T>
243bool operator!=(const IntrusiveRefCntPtr<T> &A, std::nullptr_t B) {
244 return !(A == B);
245}
246
247// Make IntrusiveRefCntPtr work with dyn_cast, isa, and the other idioms from
248// Casting.h.
249template <typename From> struct simplify_type;
250
251template <class T> struct simplify_type<IntrusiveRefCntPtr<T>> {
252 using SimpleType = T *;
253
254 static SimpleType getSimplifiedValue(IntrusiveRefCntPtr<T> &Val) {
255 return Val.get();
256 }
257};
258
259template <class T> struct simplify_type<const IntrusiveRefCntPtr<T>> {
260 using SimpleType = /*const*/ T *;
261
262 static SimpleType getSimplifiedValue(const IntrusiveRefCntPtr<T> &Val) {
263 return Val.get();
264 }
265};
266
267} // end namespace llvm
268
269#endif // LLVM_ADT_INTRUSIVEREFCNTPTR_H
270