Home | History | Annotate | Download | only in memory 
      1 // Copyright (c) 2012 The Chromium 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 #ifndef BASE_MEMORY_REF_COUNTED_H_
      6 #define BASE_MEMORY_REF_COUNTED_H_
      7 
      8 #include <stddef.h>
      9 
     10 #include <utility>
     11 
     12 #include "base/atomic_ref_count.h"
     13 #include "base/base_export.h"
     14 #include "base/compiler_specific.h"
     15 #include "base/logging.h"
     16 #include "base/macros.h"
     17 #include "base/memory/scoped_refptr.h"
     18 #include "base/sequence_checker.h"
     19 #include "base/threading/thread_collision_warner.h"
     20 #include "build/build_config.h"
     21 
     22 namespace base {
     23 namespace subtle {
     24 
     25 class BASE_EXPORT RefCountedBase {
     26  public:
     27   bool HasOneRef() const { return ref_count_ == 1; }
     28 
     29  protected:
     30   explicit RefCountedBase(StartRefCountFromZeroTag) {
     31 #if DCHECK_IS_ON()
     32     sequence_checker_.DetachFromSequence();
     33 #endif
     34   }
     35 
     36   explicit RefCountedBase(StartRefCountFromOneTag) : ref_count_(1) {
     37 #if DCHECK_IS_ON()
     38     needs_adopt_ref_ = true;
     39     sequence_checker_.DetachFromSequence();
     40 #endif
     41   }
     42 
     43   ~RefCountedBase() {
     44 #if DCHECK_IS_ON()
     45     DCHECK(in_dtor_) << "RefCounted object deleted without calling Release()";
     46 #endif
     47   }
     48 
     49   void AddRef() const {
     50     // TODO(maruel): Add back once it doesn't assert 500 times/sec.
     51     // Current thread books the critical section "AddRelease"
     52     // without release it.
     53     // DFAKE_SCOPED_LOCK_THREAD_LOCKED(add_release_);
     54 #if DCHECK_IS_ON()
     55     DCHECK(!in_dtor_);
     56     DCHECK(!needs_adopt_ref_)
     57         << "This RefCounted object is created with non-zero reference count."
     58         << " The first reference to such a object has to be made by AdoptRef or"
     59         << " MakeRefCounted.";
     60     if (ref_count_ >= 1) {
     61       DCHECK(CalledOnValidSequence());
     62     }
     63 #endif
     64 
     65     AddRefImpl();
     66   }
     67 
     68   // Returns true if the object should self-delete.
     69   bool Release() const {
     70     --ref_count_;
     71 
     72     // TODO(maruel): Add back once it doesn't assert 500 times/sec.
     73     // Current thread books the critical section "AddRelease"
     74     // without release it.
     75     // DFAKE_SCOPED_LOCK_THREAD_LOCKED(add_release_);
     76 
     77 #if DCHECK_IS_ON()
     78     DCHECK(!in_dtor_);
     79     if (ref_count_ == 0)
     80       in_dtor_ = true;
     81 
     82     if (ref_count_ >= 1)
     83       DCHECK(CalledOnValidSequence());
     84     if (ref_count_ == 1)
     85       sequence_checker_.DetachFromSequence();
     86 #endif
     87 
     88     return ref_count_ == 0;
     89   }
     90 
     91   // Returns true if it is safe to read or write the object, from a thread
     92   // safety standpoint. Should be DCHECK'd from the methods of RefCounted
     93   // classes if there is a danger of objects being shared across threads.
     94   //
     95   // This produces fewer false positives than adding a separate SequenceChecker
     96   // into the subclass, because it automatically detaches from the sequence when
     97   // the reference count is 1 (and never fails if there is only one reference).
     98   //
     99   // This means unlike a separate SequenceChecker, it will permit a singly
    100   // referenced object to be passed between threads (not holding a reference on
    101   // the sending thread), but will trap if the sending thread holds onto a
    102   // reference, or if the object is accessed from multiple threads
    103   // simultaneously.
    104   bool IsOnValidSequence() const {
    105 #if DCHECK_IS_ON()
    106     return ref_count_ <= 1 || CalledOnValidSequence();
    107 #else
    108     return true;
    109 #endif
    110   }
    111 
    112  private:
    113   template <typename U>
    114   friend scoped_refptr<U> base::AdoptRef(U*);
    115 
    116   void Adopted() const {
    117 #if DCHECK_IS_ON()
    118     DCHECK(needs_adopt_ref_);
    119     needs_adopt_ref_ = false;
    120 #endif
    121   }
    122 
    123 #if defined(ARCH_CPU_64_BIT)
    124   void AddRefImpl() const;
    125 #else
    126   void AddRefImpl() const { ++ref_count_; }
    127 #endif
    128 
    129 #if DCHECK_IS_ON()
    130   bool CalledOnValidSequence() const;
    131 #endif
    132 
    133   mutable uint32_t ref_count_ = 0;
    134 
    135 #if DCHECK_IS_ON()
    136   mutable bool needs_adopt_ref_ = false;
    137   mutable bool in_dtor_ = false;
    138   mutable SequenceChecker sequence_checker_;
    139 #endif
    140 
    141   DFAKE_MUTEX(add_release_);
    142 
    143   DISALLOW_COPY_AND_ASSIGN(RefCountedBase);
    144 };
    145 
    146 class BASE_EXPORT RefCountedThreadSafeBase {
    147  public:
    148   bool HasOneRef() const;
    149 
    150  protected:
    151   explicit constexpr RefCountedThreadSafeBase(StartRefCountFromZeroTag) {}
    152   explicit constexpr RefCountedThreadSafeBase(StartRefCountFromOneTag)
    153       : ref_count_(1) {
    154 #if DCHECK_IS_ON()
    155     needs_adopt_ref_ = true;
    156 #endif
    157   }
    158 
    159 #if DCHECK_IS_ON()
    160   ~RefCountedThreadSafeBase();
    161 #else
    162   ~RefCountedThreadSafeBase() = default;
    163 #endif
    164 
    165 // Release and AddRef are suitable for inlining on X86 because they generate
    166 // very small code sequences. On other platforms (ARM), it causes a size
    167 // regression and is probably not worth it.
    168 #if defined(ARCH_CPU_X86_FAMILY)
    169   // Returns true if the object should self-delete.
    170   bool Release() const { return ReleaseImpl(); }
    171   void AddRef() const { AddRefImpl(); }
    172 #else
    173   // Returns true if the object should self-delete.
    174   bool Release() const;
    175   void AddRef() const;
    176 #endif
    177 
    178  private:
    179   template <typename U>
    180   friend scoped_refptr<U> base::AdoptRef(U*);
    181 
    182   void Adopted() const {
    183 #if DCHECK_IS_ON()
    184     DCHECK(needs_adopt_ref_);
    185     needs_adopt_ref_ = false;
    186 #endif
    187   }
    188 
    189   ALWAYS_INLINE void AddRefImpl() const {
    190 #if DCHECK_IS_ON()
    191     DCHECK(!in_dtor_);
    192     DCHECK(!needs_adopt_ref_)
    193         << "This RefCounted object is created with non-zero reference count."
    194         << " The first reference to such a object has to be made by AdoptRef or"
    195         << " MakeRefCounted.";
    196 #endif
    197     ref_count_.Increment();
    198   }
    199 
    200   ALWAYS_INLINE bool ReleaseImpl() const {
    201 #if DCHECK_IS_ON()
    202     DCHECK(!in_dtor_);
    203     DCHECK(!ref_count_.IsZero());
    204 #endif
    205     if (!ref_count_.Decrement()) {
    206 #if DCHECK_IS_ON()
    207       in_dtor_ = true;
    208 #endif
    209       return true;
    210     }
    211     return false;
    212   }
    213 
    214   mutable AtomicRefCount ref_count_{0};
    215 #if DCHECK_IS_ON()
    216   mutable bool needs_adopt_ref_ = false;
    217   mutable bool in_dtor_ = false;
    218 #endif
    219 
    220   DISALLOW_COPY_AND_ASSIGN(RefCountedThreadSafeBase);
    221 };
    222 
    223 }  // namespace subtle
    224 
    225 // ScopedAllowCrossThreadRefCountAccess disables the check documented on
    226 // RefCounted below for rare pre-existing use cases where thread-safety was
    227 // guaranteed through other means (e.g. explicit sequencing of calls across
    228 // execution sequences when bouncing between threads in order). New callers
    229 // should refrain from using this (callsites handling thread-safety through
    230 // locks should use RefCountedThreadSafe per the overhead of its atomics being
    231 // negligible compared to locks anyways and callsites doing explicit sequencing
    232 // should properly std::move() the ref to avoid hitting this check).
    233 // TODO(tzik): Cleanup existing use cases and remove
    234 // ScopedAllowCrossThreadRefCountAccess.
    235 class BASE_EXPORT ScopedAllowCrossThreadRefCountAccess final {
    236  public:
    237 #if DCHECK_IS_ON()
    238   ScopedAllowCrossThreadRefCountAccess();
    239   ~ScopedAllowCrossThreadRefCountAccess();
    240 #else
    241   ScopedAllowCrossThreadRefCountAccess() {}
    242   ~ScopedAllowCrossThreadRefCountAccess() {}
    243 #endif
    244 };
    245 
    246 //
    247 // A base class for reference counted classes.  Otherwise, known as a cheap
    248 // knock-off of WebKit's RefCounted<T> class.  To use this, just extend your
    249 // class from it like so:
    250 //
    251 //   class MyFoo : public base::RefCounted<MyFoo> {
    252 //    ...
    253 //    private:
    254 //     friend class base::RefCounted<MyFoo>;
    255 //     ~MyFoo();
    256 //   };
    257 //
    258 // You should always make your destructor non-public, to avoid any code deleting
    259 // the object accidently while there are references to it.
    260 //
    261 //
    262 // The ref count manipulation to RefCounted is NOT thread safe and has DCHECKs
    263 // to trap unsafe cross thread usage. A subclass instance of RefCounted can be
    264 // passed to another execution sequence only when its ref count is 1. If the ref
    265 // count is more than 1, the RefCounted class verifies the ref updates are made
    266 // on the same execution sequence as the previous ones. The subclass can also
    267 // manually call IsOnValidSequence to trap other non-thread-safe accesses; see
    268 // the documentation for that method.
    269 //
    270 //
    271 // The reference count starts from zero by default, and we intended to migrate
    272 // to start-from-one ref count. Put REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE() to
    273 // the ref counted class to opt-in.
    274 //
    275 // If an object has start-from-one ref count, the first scoped_refptr need to be
    276 // created by base::AdoptRef() or base::MakeRefCounted(). We can use
    277 // base::MakeRefCounted() to create create both type of ref counted object.
    278 //
    279 // The motivations to use start-from-one ref count are:
    280 //  - Start-from-one ref count doesn't need the ref count increment for the
    281 //    first reference.
    282 //  - It can detect an invalid object acquisition for a being-deleted object
    283 //    that has zero ref count. That tends to happen on custom deleter that
    284 //    delays the deletion.
    285 //    TODO(tzik): Implement invalid acquisition detection.
    286 //  - Behavior parity to Blink's WTF::RefCounted, whose count starts from one.
    287 //    And start-from-one ref count is a step to merge WTF::RefCounted into
    288 //    base::RefCounted.
    289 //
    290 #define REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE()             \
    291   static constexpr ::base::subtle::StartRefCountFromOneTag \
    292       kRefCountPreference = ::base::subtle::kStartRefCountFromOneTag
    293 
    294 template <class T, typename Traits>
    295 class RefCounted;
    296 
    297 template <typename T>
    298 struct DefaultRefCountedTraits {
    299   static void Destruct(const T* x) {
    300     RefCounted<T, DefaultRefCountedTraits>::DeleteInternal(x);
    301   }
    302 };
    303 
    304 template <class T, typename Traits = DefaultRefCountedTraits<T>>
    305 class RefCounted : public subtle::RefCountedBase {
    306  public:
    307   static constexpr subtle::StartRefCountFromZeroTag kRefCountPreference =
    308       subtle::kStartRefCountFromZeroTag;
    309 
    310   RefCounted() : subtle::RefCountedBase(T::kRefCountPreference) {}
    311 
    312   void AddRef() const {
    313     subtle::RefCountedBase::AddRef();
    314   }
    315 
    316   void Release() const {
    317     if (subtle::RefCountedBase::Release()) {
    318       // Prune the code paths which the static analyzer may take to simulate
    319       // object destruction. Use-after-free errors aren't possible given the
    320       // lifetime guarantees of the refcounting system.
    321       ANALYZER_SKIP_THIS_PATH();
    322 
    323       Traits::Destruct(static_cast<const T*>(this));
    324     }
    325   }
    326 
    327  protected:
    328   ~RefCounted() = default;
    329 
    330  private:
    331   friend struct DefaultRefCountedTraits<T>;
    332   template <typename U>
    333   static void DeleteInternal(const U* x) {
    334     delete x;
    335   }
    336 
    337   DISALLOW_COPY_AND_ASSIGN(RefCounted);
    338 };
    339 
    340 // Forward declaration.
    341 template <class T, typename Traits> class RefCountedThreadSafe;
    342 
    343 // Default traits for RefCountedThreadSafe<T>.  Deletes the object when its ref
    344 // count reaches 0.  Overload to delete it on a different thread etc.
    345 template<typename T>
    346 struct DefaultRefCountedThreadSafeTraits {
    347   static void Destruct(const T* x) {
    348     // Delete through RefCountedThreadSafe to make child classes only need to be
    349     // friend with RefCountedThreadSafe instead of this struct, which is an
    350     // implementation detail.
    351     RefCountedThreadSafe<T,
    352                          DefaultRefCountedThreadSafeTraits>::DeleteInternal(x);
    353   }
    354 };
    355 
    356 //
    357 // A thread-safe variant of RefCounted<T>
    358 //
    359 //   class MyFoo : public base::RefCountedThreadSafe<MyFoo> {
    360 //    ...
    361 //   };
    362 //
    363 // If you're using the default trait, then you should add compile time
    364 // asserts that no one else is deleting your object.  i.e.
    365 //    private:
    366 //     friend class base::RefCountedThreadSafe<MyFoo>;
    367 //     ~MyFoo();
    368 //
    369 // We can use REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE() with RefCountedThreadSafe
    370 // too. See the comment above the RefCounted definition for details.
    371 template <class T, typename Traits = DefaultRefCountedThreadSafeTraits<T> >
    372 class RefCountedThreadSafe : public subtle::RefCountedThreadSafeBase {
    373  public:
    374   static constexpr subtle::StartRefCountFromZeroTag kRefCountPreference =
    375       subtle::kStartRefCountFromZeroTag;
    376 
    377   explicit RefCountedThreadSafe()
    378       : subtle::RefCountedThreadSafeBase(T::kRefCountPreference) {}
    379 
    380   void AddRef() const {
    381     subtle::RefCountedThreadSafeBase::AddRef();
    382   }
    383 
    384   void Release() const {
    385     if (subtle::RefCountedThreadSafeBase::Release()) {
    386       ANALYZER_SKIP_THIS_PATH();
    387       Traits::Destruct(static_cast<const T*>(this));
    388     }
    389   }
    390 
    391  protected:
    392   ~RefCountedThreadSafe() = default;
    393 
    394  private:
    395   friend struct DefaultRefCountedThreadSafeTraits<T>;
    396   template <typename U>
    397   static void DeleteInternal(const U* x) {
    398     delete x;
    399   }
    400 
    401   DISALLOW_COPY_AND_ASSIGN(RefCountedThreadSafe);
    402 };
    403 
    404 //
    405 // A thread-safe wrapper for some piece of data so we can place other
    406 // things in scoped_refptrs<>.
    407 //
    408 template<typename T>
    409 class RefCountedData
    410     : public base::RefCountedThreadSafe< base::RefCountedData<T> > {
    411  public:
    412   RefCountedData() : data() {}
    413   RefCountedData(const T& in_value) : data(in_value) {}
    414   RefCountedData(T&& in_value) : data(std::move(in_value)) {}
    415 
    416   T data;
    417 
    418  private:
    419   friend class base::RefCountedThreadSafe<base::RefCountedData<T> >;
    420   ~RefCountedData() = default;
    421 };
    422 
    423 }  // namespace base
    424 
    425 #endif  // BASE_MEMORY_REF_COUNTED_H_
    426