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