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