1 // Copyright 2013 The Flutter 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 FLUTTER_FML_PLATFORM_DARWIN_SCOPED_NSOBJECT_H_
6 #define FLUTTER_FML_PLATFORM_DARWIN_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 "flutter/fml/compiler_specific.h"
14 #include "flutter/fml/macros.h"
15
16 @class NSAutoreleasePool;
17
18 namespace fml {
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:
object_(object)43 explicit scoped_nsprotocol(NST object = nil) : object_(object) {}
44
scoped_nsprotocol(const scoped_nsprotocol<NST> & that)45 scoped_nsprotocol(const scoped_nsprotocol<NST>& that) : object_([that.object_ retain]) {}
46
47 template <typename NSU>
scoped_nsprotocol(const scoped_nsprotocol<NSU> & that)48 scoped_nsprotocol(const scoped_nsprotocol<NSU>& that) : object_([that.get() retain]) {}
49
~scoped_nsprotocol()50 ~scoped_nsprotocol() { [object_ release]; }
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
NST()69 operator NST() const { return object_; }
70
get()71 NST get() const { return object_; }
72
swap(scoped_nsprotocol & that)73 void swap(scoped_nsprotocol& that) {
74 NST temp = that.object_;
75 that.object_ = object_;
76 object_ = temp;
77 }
78
79 // scoped_nsprotocol<>::release() is like scoped_ptr<>::release. It is NOT a
80 // wrapper for [object_ release]. To force a scoped_nsprotocol<> to call
81 // [object_ release], use scoped_nsprotocol<>::reset().
release()82 NST release() FML_WARN_UNUSED_RESULT {
83 NST temp = object_;
84 object_ = nil;
85 return temp;
86 }
87
88 // Shift reference to the autorelease pool to be released later.
autorelease()89 NST autorelease() { return [release() autorelease]; }
90
91 private:
92 NST object_;
93 };
94
95 // Free functions
96 template <class C>
swap(scoped_nsprotocol<C> & p1,scoped_nsprotocol<C> & p2)97 void swap(scoped_nsprotocol<C>& p1, scoped_nsprotocol<C>& p2) {
98 p1.swap(p2);
99 }
100
101 template <class C>
102 bool operator==(C p1, const scoped_nsprotocol<C>& p2) {
103 return p1 == p2.get();
104 }
105
106 template <class C>
107 bool operator!=(C p1, const scoped_nsprotocol<C>& p2) {
108 return p1 != p2.get();
109 }
110
111 template <typename NST>
112 class scoped_nsobject : public scoped_nsprotocol<NST*> {
113 public:
114 explicit scoped_nsobject(NST* object = nil) : scoped_nsprotocol<NST*>(object) {}
115
scoped_nsobject(const scoped_nsobject<NST> & that)116 scoped_nsobject(const scoped_nsobject<NST>& that) : scoped_nsprotocol<NST*>(that) {}
117
118 template <typename NSU>
scoped_nsobject(const scoped_nsobject<NSU> & that)119 scoped_nsobject(const scoped_nsobject<NSU>& that) : scoped_nsprotocol<NST*>(that) {}
120
121 scoped_nsobject& operator=(const scoped_nsobject<NST>& that) {
122 scoped_nsprotocol<NST*>::operator=(that);
123 return *this;
124 }
125 };
126
127 // Specialization to make scoped_nsobject<id> work.
128 template <>
129 class scoped_nsobject<id> : public scoped_nsprotocol<id> {
130 public:
131 explicit scoped_nsobject(id object = nil) : scoped_nsprotocol<id>(object) {}
132
scoped_nsobject(const scoped_nsobject<id> & that)133 scoped_nsobject(const scoped_nsobject<id>& that) : scoped_nsprotocol<id>(that) {}
134
135 template <typename NSU>
scoped_nsobject(const scoped_nsobject<NSU> & that)136 scoped_nsobject(const scoped_nsobject<NSU>& that) : scoped_nsprotocol<id>(that) {}
137
138 scoped_nsobject& operator=(const scoped_nsobject<id>& that) {
139 scoped_nsprotocol<id>::operator=(that);
140 return *this;
141 }
142 };
143
144 // Do not use scoped_nsobject for NSAutoreleasePools, use
145 // ScopedNSAutoreleasePool instead. This is a compile time check. See details
146 // at top of header.
147 template <>
148 class scoped_nsobject<NSAutoreleasePool> {
149 private:
150 explicit scoped_nsobject(NSAutoreleasePool* object = nil);
151 FML_DISALLOW_COPY_AND_ASSIGN(scoped_nsobject);
152 };
153
154 } // namespace fml
155
156 #endif // FLUTTER_FML_PLATFORM_DARWIN_SCOPED_NSOBJECT_H_
157