include/core/SkWeakRefCnt.h

   1 /*
   2  * Copyright 2012 Google Inc.
   3  *
   4  * Use of this source code is governed by a BSD-style license that can be
   5  * found in the LICENSE file.
   6  */
   7
   8 #ifndef SkWeakRefCnt_DEFINED
   9 #define SkWeakRefCnt_DEFINED
  10
  11 #include "SkRefCnt.h"
  12 #include "SkThread.h"
  13
  14 /** \class SkWeakRefCnt
  15
  16     SkWeakRefCnt is the base class for objects that may be shared by multiple
  17     objects. When an existing strong owner wants to share a reference, it calls
  18     ref(). When a strong owner wants to release its reference, it calls
  19     unref(). When the shared object's strong reference count goes to zero as
  20     the result of an unref() call, its (virtual) weak_dispose method is called.
  21     It is an error for the destructor to be called explicitly (or via the
  22     object going out of scope on the stack or calling delete) if
  23     getRefCnt() > 1.
  24
  25     In addition to strong ownership, an owner may instead obtain a weak
  26     reference by calling weak_ref(). A call to weak_ref() must be balanced by a
  27     call to weak_unref(). To obtain a strong reference from a weak reference,
  28     call try_ref(). If try_ref() returns true, the owner's pointer is now also
  29     a strong reference on which unref() must be called. Note that this does not
  30     affect the original weak reference, weak_unref() must still be called. When
  31     the weak reference count goes to zero, the object is deleted. While the
  32     weak reference count is positive and the strong reference count is zero the
  33     object still exists, but will be in the disposed state. It is up to the
  34     object to define what this means.
  35
  36     Note that a strong reference implicitly implies a weak reference. As a
  37     result, it is allowable for the owner of a strong ref to call try_ref().
  38     This will have the same effect as calling ref(), but may be more expensive.
  39
  40     Example:
  41
  42     SkWeakRefCnt myRef = strongRef.weak_ref();
  43     ... // strongRef.unref() may or may not be called
  44     if (myRef.try_ref()) {
  45         ... // use myRef
  46         myRef.unref();
  47     } else {
  48         // myRef is in the disposed state
  49     }
  50     myRef.weak_unref();
  51 */
  52 class SK_API SkWeakRefCnt : public SkRefCnt {
  53 public:
  54     SK_DECLARE_INST_COUNT(SkWeakRefCnt)
  55
  56     /** Default construct, initializing the reference counts to 1.
  57         The strong references collectively hold one weak reference. When the
  58         strong reference count goes to zero, the collectively held weak
  59         reference is released.
  60     */
  61     SkWeakRefCnt() : SkRefCnt(), fWeakCnt(1) {}
  62
  63     /** Destruct, asserting that the weak reference count is 1.
  64     */
  65     virtual ~SkWeakRefCnt() {
  66 #ifdef SK_DEBUG
  67         SkASSERT(fWeakCnt == 1);
  68         fWeakCnt = 0;
  69 #endif
  70     }
  71
  72     /** Return the weak reference count.
  73     */
  74     int32_t getWeakCnt() const { return fWeakCnt; }
  75
  76 #ifdef SK_DEBUG
  77     void validate() const {
  78         this->INHERITED::validate();
  79         SkASSERT(fWeakCnt > 0);
  80     }
  81 #endif
  82
  83     /** Creates a strong reference from a weak reference, if possible. The
  84         caller must already be an owner. If try_ref() returns true the owner
  85         is in posession of an additional strong reference. Both the original
  86         reference and new reference must be properly unreferenced. If try_ref()
  87         returns false, no strong reference could be created and the owner's
  88         reference is in the same state as before the call.
  89     */
  90     bool SK_WARN_UNUSED_RESULT try_ref() const {
  91         if (sk_atomic_conditional_inc(&fRefCnt) != 0) {
  92             // Acquire barrier (L/SL), if not provided above.
  93             // Prevents subsequent code from happening before the increment.
  94             sk_membar_acquire__after_atomic_conditional_inc();
  95             return true;
  96         }
  97         return false;
  98     }
  99
 100     /** Increment the weak reference count. Must be balanced by a call to
 101         weak_unref().
 102     */
 103     void weak_ref() const {
 104         SkASSERT(fRefCnt > 0);
 105         SkASSERT(fWeakCnt > 0);
 106         sk_atomic_inc(&fWeakCnt);  // No barrier required.
 107     }
 108
 109     /** Decrement the weak reference count. If the weak reference count is 1
 110         before the decrement, then call delete on the object. Note that if this
 111         is the case, then the object needs to have been allocated via new, and
 112         not on the stack.
 113     */
 114     void weak_unref() const {
 115         SkASSERT(fWeakCnt > 0);
 116         // Release barrier (SL/S), if not provided below.
 117         if (sk_atomic_dec(&fWeakCnt) == 1) {
 118             // Acquire barrier (L/SL), if not provided above.
 119             // Prevents code in destructor from happening before the decrement.
 120             sk_membar_acquire__after_atomic_dec();
 121 #ifdef SK_DEBUG
 122             // so our destructor won't complain
 123             fWeakCnt = 1;
 124 #endif
 125             this->INHERITED::internal_dispose();
 126         }
 127     }
 128
 129     /** Returns true if there are no strong references to the object. When this
 130         is the case all future calls to try_ref() will return false.
 131     */
 132     bool weak_expired() const {
 133         return fRefCnt == 0;
 134     }
 135
 136 protected:
 137     /** Called when the strong reference count goes to zero. This allows the
 138         object to free any resources it may be holding. Weak references may
 139         still exist and their level of allowed access to the object is defined
 140         by the object's class.
 141     */
 142     virtual void weak_dispose() const {
 143     }
 144
 145 private:
 146     /** Called when the strong reference count goes to zero. Calls weak_dispose
 147         on the object and releases the implicit weak reference held
 148         collectively by the strong references.
 149     */
 150     void internal_dispose() const SK_OVERRIDE {
 151         weak_dispose();
 152         weak_unref();
 153     }
 154
 155     /* Invariant: fWeakCnt = #weak + (fRefCnt > 0 ? 1 : 0) */
 156     mutable int32_t fWeakCnt;
 157
 158     typedef SkRefCnt INHERITED;
 159 };
 160
 161 #endif