base/ios/weak_nsobject.h

   1 // Copyright 2013 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_IOS_WEAK_NSOBJECT_H_
   6 #define BASE_IOS_WEAK_NSOBJECT_H_
   7
   8 #import <Foundation/Foundation.h>
   9 #import <objc/runtime.h>
  10
  11 #include "base/basictypes.h"
  12 #include "base/compiler_specific.h"
  13 #include "base/logging.h"
  14 #include "base/memory/ref_counted.h"
  15 #include "base/threading/non_thread_safe.h"
  16 #include "base/threading/thread_checker.h"
  17
  18 // WeakNSObject<> is patterned after scoped_nsobject<>, but instead of
  19 // maintaining ownership of an NSObject subclass object, it will nil itself out
  20 // when the object is deallocated.
  21 //
  22 // WeakNSProtocol<> has the same behavior as WeakNSObject, but can be used
  23 // with protocols.
  24 //
  25 // Example usage (base::WeakNSObject<T>):
  26 //   scoped_nsobject<Foo> foo([[Foo alloc] init]);
  27 //   WeakNSObject<Foo> weak_foo;  // No pointer
  28 //   weak_foo.reset(foo)  // Now a weak reference is kept.
  29 //   [weak_foo description];  // Returns [foo description].
  30 //   foo.reset();  // The reference is released.
  31 //   [weak_foo description];  // Returns nil, as weak_foo is pointing to nil.
  32 //
  33 //
  34 // Implementation wise a WeakNSObject keeps a reference to a refcounted
  35 // WeakContainer. There is one unique instance of a WeakContainer per watched
  36 // NSObject, this relationship is maintained via the ObjectiveC associated
  37 // object API, indirectly via an ObjectiveC CRBWeakNSProtocolSentinel class.
  38 //
  39 // Threading restrictions:
  40 // - Several WeakNSObject pointing to the same underlying object must all be
  41 //   created and dereferenced on the same thread;
  42 // - thread safety is enforced by the implementation, except in two cases:
  43 //   (1) it is allowed to copy a WeakNSObject on a different thread. However,
  44 //       that copy must return to the original thread before being dereferenced,
  45 //   (2) it is allowed to destroy a WeakNSObject on any thread;
  46 // - the implementation assumes that the tracked object will be released on the
  47 //   same thread that the WeakNSObject is created on.
  48 namespace base {
  49
  50 // WeakContainer keeps a weak pointer to an object and clears it when it
  51 // receives nullify() from the object's sentinel.
  52 class WeakContainer : public base::RefCountedThreadSafe<WeakContainer> {
  53  public:
  54   explicit WeakContainer(id object) : object_(object) {}
  55
  56   id object() {
  57     DCHECK(checker_.CalledOnValidThread());
  58     return object_;
  59   }
  60
  61   void nullify() {
  62     DCHECK(checker_.CalledOnValidThread());
  63     object_ = nil;
  64   }
  65
  66  private:
  67   friend base::RefCountedThreadSafe<WeakContainer>;
  68   ~WeakContainer() {}
  69   base::ThreadChecker checker_;
  70   id object_;
  71 };
  72
  73 }  // namespace base
  74
  75 // Sentinel for observing the object contained in the weak pointer. The object
  76 // will be deleted when the weak object is deleted and will notify its
  77 // container.
  78 @interface CRBWeakNSProtocolSentinel : NSObject
  79 // Return the only associated container for this object. There can be only one.
  80 // Will return null if object is nil .
  81 + (scoped_refptr<base::WeakContainer>)containerForObject:(id)object;
  82 @end
  83
  84 namespace base {
  85
  86 // Base class for all WeakNSObject derivatives.
  87 template <typename NST>
  88 class WeakNSProtocol {
  89  public:
  90   explicit WeakNSProtocol(NST object = nil) {
  91     container_ = [CRBWeakNSProtocolSentinel containerForObject:object];
  92   }
  93
  94   WeakNSProtocol(const WeakNSProtocol<NST>& that) {
  95     // A WeakNSProtocol object can be copied on one thread and used on
  96     // another.
  97     checker_.DetachFromThread();
  98     container_ = that.container_;
  99   }
 100
 101   ~WeakNSProtocol() {
 102     // A WeakNSProtocol object can be used on one thread and released on
 103     // another. This is not the case for the contained object.
 104     checker_.DetachFromThread();
 105   }
 106
 107   void reset(NST object = nil) {
 108     DCHECK(checker_.CalledOnValidThread());
 109     container_ = [CRBWeakNSProtocolSentinel containerForObject:object];
 110   }
 111
 112   NST get() const {
 113     DCHECK(checker_.CalledOnValidThread());
 114     if (!container_.get())
 115       return nil;
 116     return container_->object();
 117   }
 118
 119   WeakNSProtocol& operator=(const WeakNSProtocol<NST>& that) {
 120     DCHECK(checker_.CalledOnValidThread());
 121     container_ = that.container_;
 122     return *this;
 123   }
 124
 125   bool operator==(NST that) const {
 126     DCHECK(checker_.CalledOnValidThread());
 127     return get() == that;
 128   }
 129
 130   bool operator!=(NST that) const {
 131     DCHECK(checker_.CalledOnValidThread());
 132     return get() != that;
 133   }
 134
 135   operator NST() const {
 136     DCHECK(checker_.CalledOnValidThread());
 137     return get();
 138   }
 139
 140  private:
 141   // Refecounted reference to the container tracking the ObjectiveC object this
 142   // class encapsulates.
 143   scoped_refptr<base::WeakContainer> container_;
 144   base::ThreadChecker checker_;
 145 };
 146
 147 // Free functions
 148 template <class NST>
 149 bool operator==(NST p1, const WeakNSProtocol<NST>& p2) {
 150   return p1 == p2.get();
 151 }
 152
 153 template <class NST>
 154 bool operator!=(NST p1, const WeakNSProtocol<NST>& p2) {
 155   return p1 != p2.get();
 156 }
 157
 158 template <typename NST>
 159 class WeakNSObject : public WeakNSProtocol<NST*> {
 160  public:
 161   explicit WeakNSObject(NST* object = nil) : WeakNSProtocol<NST*>(object) {}
 162
 163   WeakNSObject(const WeakNSObject<NST>& that) : WeakNSProtocol<NST*>(that) {}
 164
 165   WeakNSObject& operator=(const WeakNSObject<NST>& that) {
 166     WeakNSProtocol<NST*>::operator=(that);
 167     return *this;
 168   }
 169 };
 170
 171 // Specialization to make WeakNSObject<id> work.
 172 template <>
 173 class WeakNSObject<id> : public WeakNSProtocol<id> {
 174  public:
 175   explicit WeakNSObject(id object = nil) : WeakNSProtocol<id>(object) {}
 176
 177   WeakNSObject(const WeakNSObject<id>& that) : WeakNSProtocol<id>(that) {}
 178
 179   WeakNSObject& operator=(const WeakNSObject<id>& that) {
 180     WeakNSProtocol<id>::operator=(that);
 181     return *this;
 182   }
 183 };
 184
 185 }  // namespace base
 186
 187 #endif  // BASE_IOS_WEAK_NSOBJECT_H_