base/mac/scoped_nsobject.h

   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_MAC_SCOPED_NSOBJECT_H_
   6 #define BASE_MAC_SCOPED_NSOBJECT_H_
   7
   8 // Include NSObject.h directly because Foundation.h pulls in many dependencies.
   9 // (Approx 100k lines of code versus 1.5k for NSObject.h). scoped_nsobject gets
  10 // singled out because it is most typically included from other header files.
  11 #import <Foundation/NSObject.h>
  12
  13 #include "base/basictypes.h"
  14 #include "base/compiler_specific.h"
  15
  16 @class NSAutoreleasePool;
  17
  18 namespace base {
  19
  20 // scoped_nsobject<> is patterned after scoped_ptr<>, but maintains ownership
  21 // of an NSObject subclass object.  Style deviations here are solely for
  22 // compatibility with scoped_ptr<>'s interface, with which everyone is already
  23 // familiar.
  24 //
  25 // scoped_nsobject<> takes ownership of an object (in the constructor or in
  26 // reset()) by taking over the caller's existing ownership claim.  The caller
  27 // must own the object it gives to scoped_nsobject<>, and relinquishes an
  28 // ownership claim to that object.  scoped_nsobject<> does not call -retain,
  29 // callers have to call this manually if appropriate.
  30 //
  31 // scoped_nsprotocol<> has the same behavior as scoped_nsobject, but can be used
  32 // with protocols.
  33 //
  34 // scoped_nsobject<> is not to be used for NSAutoreleasePools. For
  35 // NSAutoreleasePools use ScopedNSAutoreleasePool from
  36 // scoped_nsautorelease_pool.h instead.
  37 // We check for bad uses of scoped_nsobject and NSAutoreleasePool at compile
  38 // time with a template specialization (see below).
  39
  40 template<typename NST>
  41 class scoped_nsprotocol {
  42  public:
  43   explicit scoped_nsprotocol(NST object = nil) : object_(object) {}
  44
  45   scoped_nsprotocol(const scoped_nsprotocol<NST>& that)
  46       : object_([that.object_ retain]) {
  47   }
  48
  49   template <typename NSU>
  50   scoped_nsprotocol(const scoped_nsprotocol<NSU>& that)
  51       : object_([that.get() retain]) {
  52   }
  53
  54   ~scoped_nsprotocol() {
  55     [object_ release];
  56   }
  57
  58   scoped_nsprotocol& operator=(const scoped_nsprotocol<NST>& that) {
  59     reset([that.get() retain]);
  60     return *this;
  61   }
  62
  63   void reset(NST object = nil) {
  64     // We intentionally do not check that object != object_ as the caller must
  65     // either already have an ownership claim over whatever it passes to this
  66     // method, or call it with the |RETAIN| policy which will have ensured that
  67     // the object is retained once more when reaching this point.
  68     [object_ release];
  69     object_ = object;
  70   }
  71
  72   bool operator==(NST that) const { return object_ == that; }
  73   bool operator!=(NST that) const { return object_ != that; }
  74
  75   operator NST() const {
  76     return object_;
  77   }
  78
  79   NST get() const {
  80     return object_;
  81   }
  82
  83   void swap(scoped_nsprotocol& that) {
  84     NST temp = that.object_;
  85     that.object_ = object_;
  86     object_ = temp;
  87   }
  88
  89   // scoped_nsprotocol<>::release() is like scoped_ptr<>::release.  It is NOT a
  90   // wrapper for [object_ release].  To force a scoped_nsprotocol<> to call
  91   // [object_ release], use scoped_nsprotocol<>::reset().
  92   NST release() WARN_UNUSED_RESULT {
  93     NST temp = object_;
  94     object_ = nil;
  95     return temp;
  96   }
  97
  98   // Shift reference to the autorelease pool to be released later.
  99   NST autorelease() {
 100     return [release() autorelease];
 101   }
 102
 103  private:
 104   NST object_;
 105 };
 106
 107 // Free functions
 108 template <class C>
 109 void swap(scoped_nsprotocol<C>& p1, scoped_nsprotocol<C>& p2) {
 110   p1.swap(p2);
 111 }
 112
 113 template <class C>
 114 bool operator==(C p1, const scoped_nsprotocol<C>& p2) {
 115   return p1 == p2.get();
 116 }
 117
 118 template <class C>
 119 bool operator!=(C p1, const scoped_nsprotocol<C>& p2) {
 120   return p1 != p2.get();
 121 }
 122
 123 template<typename NST>
 124 class scoped_nsobject : public scoped_nsprotocol<NST*> {
 125  public:
 126   explicit scoped_nsobject(NST* object = nil)
 127       : scoped_nsprotocol<NST*>(object) {}
 128
 129   scoped_nsobject(const scoped_nsobject<NST>& that)
 130       : scoped_nsprotocol<NST*>(that) {
 131   }
 132
 133   template<typename NSU>
 134   scoped_nsobject(const scoped_nsobject<NSU>& that)
 135       : scoped_nsprotocol<NST*>(that) {
 136   }
 137
 138   scoped_nsobject& operator=(const scoped_nsobject<NST>& that) {
 139     scoped_nsprotocol<NST*>::operator=(that);
 140     return *this;
 141   }
 142 };
 143
 144 // Specialization to make scoped_nsobject<id> work.
 145 template<>
 146 class scoped_nsobject<id> : public scoped_nsprotocol<id> {
 147  public:
 148   explicit scoped_nsobject(id object = nil) : scoped_nsprotocol<id>(object) {}
 149
 150   scoped_nsobject(const scoped_nsobject<id>& that)
 151       : scoped_nsprotocol<id>(that) {
 152   }
 153
 154   template<typename NSU>
 155   scoped_nsobject(const scoped_nsobject<NSU>& that)
 156       : scoped_nsprotocol<id>(that) {
 157   }
 158
 159   scoped_nsobject& operator=(const scoped_nsobject<id>& that) {
 160     scoped_nsprotocol<id>::operator=(that);
 161     return *this;
 162   }
 163 };
 164
 165 // Do not use scoped_nsobject for NSAutoreleasePools, use
 166 // ScopedNSAutoreleasePool instead. This is a compile time check. See details
 167 // at top of header.
 168 template<>
 169 class scoped_nsobject<NSAutoreleasePool> {
 170  private:
 171   explicit scoped_nsobject(NSAutoreleasePool* object = nil);
 172   DISALLOW_COPY_AND_ASSIGN(scoped_nsobject);
 173 };
 174
 175 }  // namespace base
 176
 177 #endif  // BASE_MAC_SCOPED_NSOBJECT_H_