]> git.saurik.com Git - wxWidgets.git/blob - include/wx/cocoa/ObjcRef.h
adding comment
[wxWidgets.git] / include / wx / cocoa / ObjcRef.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/cocoa/ObjcRef.h
3 // Purpose: wxObjcAutoRef template class
4 // Author: David Elliott
5 // Modified by:
6 // Created: 2004/03/28
7 // RCS-ID: $Id$
8 // Copyright: (c) 2004 David Elliott <dfe@cox.net>
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_COCOA_OBJCREF_H__
13 #define _WX_COCOA_OBJCREF_H__
14
15 // Reuse wxCFRef-related code (e.g. wxCFRetain/wxCFRelease)
16 #include "wx/osx/core/cfref.h"
17
18 // NOTE WELL: We can only know whether or not GC can be used when compiling Objective-C.
19 // Therefore we cannot implement these functions except when compiling Objective-C.
20 #ifdef __OBJC__
21 /*! @function wxGCSafeRetain
22 @templatefield Type (implicit) An Objective-C class type
23 @arg r Pointer to Objective-C object. May be null.
24 @abstract Retains the Objective-C object, even when using Apple's garbage collector
25 @discussion
26 When Apple's garbage collector is enabled, the usual [obj retain] and [obj release] messages
27 are ignored. Instead the collector with help from compiler-generated write-barriers tracks
28 reachable objects. The write-barriers are generated when setting i-vars of C++ classes but
29 they are ignored by the garbage collector unless the C++ object is in GC-managed memory.
30
31 The simple solution is to use CFRetain on the Objective-C object which has been enhanced in
32 GC mode to forcibly retain the object. In Retain/Release (RR) mode the CFRetain function has
33 the same effect as [obj retain]. Note that GC vs. RR is selected at runtime.
34
35 Take care that wxGCSafeRetain must be balanced with wxGCSafeRelease and that conversely
36 wxGCSafeRelease must only be called on objects to balance wxGCSafeRetain. In particular when
37 receiving an Objective-C object from an alloc or copy method take care that you must retain
38 it with wxGCSafeRetain and balance the initial alloc with a standard release.
39
40 Example:
41 wxGCSafeRelease(m_obj); // release current object (if any)
42 NSObject *obj = [[NSObject alloc] init];
43 m_obj = wxGCSafeRetain(obj);
44 [obj release];
45
46 Alternatively (same effect, perhaps less clear):
47 wxGCSafeRelease(m_obj); // release current object (if any)
48 m_obj = wxGCSafeRetain([[NSObject alloc] init]);
49 [m_obj release]; // balance alloc
50
51 Consider the effect on the retain count from each statement (alloc, CFRetain, release)
52 In RR mode: retainCount = 1, +1, -1
53 In GC mode: strongRetainCount = 0, +1, -0
54
55 This is a template function to ensure it is used on raw pointers and never on pointer-holder
56 objects via implicit conversion operators.
57 */
58 template <class Type>
59 inline Type * wxGCSafeRetain(Type *r)
60 {
61 #ifdef __OBJC_GC__
62 return static_cast<Type*>(wxCFRetain(r));
63 #else
64 return [r retain];
65 #endif
66 }
67
68 /*! @function wxGCSafeRelease
69 @templatefield Type (implicit) An Objective-C class type
70 @arg r Pointer to Objective-C object. May be null.
71 @abstract Balances wxGCSafeRetain. Particularly useful with the Apple Garbage Collector.
72 @discussion
73 See the wxGCSafeRetain documentation for more details.
74
75 Example (from wxGCSafeRetain documentation):
76 wxGCSafeRelease(m_obj); // release current object (if any)
77 m_obj = wxGCSafeRetain([[NSObject alloc] init]);
78 [m_obj release]; // balance alloc
79
80 When viewed from the start, m_obj ought to start as nil. However, the second time through
81 the wxGCSafeRelease call becomes critical as it releases the retain from the first time
82 through.
83
84 In the destructor for this C++ object with the m_obj i-var you ought to do the following:
85 wxGCSafeRelease(m_obj);
86 m_obj = nil; // Not strictly needed, but safer.
87
88 Under no circumstances should you balance an alloc or copy with a wxGCSafeRelease.
89 */
90 template <class Type>
91 inline void wxGCSafeRelease(Type *r)
92 {
93 #ifdef __OBJC_GC__
94 wxCFRelease(r);
95 #else
96 [r release];
97 #endif
98 }
99 #else
100 // NOTE: When not compiling Objective-C, declare these functions such that they can be
101 // used by other inline-implemented methods. Since those methods in turn will not actually
102 // be used from non-ObjC code the compiler ought not emit them. If it emits an out of
103 // line copy of those methods then presumably it will have also emitted at least one
104 // out of line copy of these functions from at least one Objective-C++ translation unit.
105 // That means the out of line implementation will be available at link time.
106
107 template <class Type>
108 inline Type * wxGCSafeRetain(Type *r);
109
110 template <class Type>
111 inline void wxGCSafeRelease(Type *r);
112
113 #endif //def __OBJC__
114
115 /*
116 wxObjcAutoRefFromAlloc: construct a reference to an object that was
117 [NSObject -alloc]'ed and thus does not need a retain
118 wxObjcAutoRef: construct a reference to an object that was
119 either autoreleased or is retained by something else.
120 */
121
122 struct objc_object;
123
124 // We must do any calls to Objective-C from an Objective-C++ source file
125 class wxObjcAutoRefBase
126 {
127 protected:
128 /*! @function ObjcRetain
129 @abstract Simply does [p retain].
130 */
131 static struct objc_object* ObjcRetain(struct objc_object*);
132
133 /*! @function ObjcRelease
134 @abstract Simply does [p release].
135 */
136 static void ObjcRelease(struct objc_object*);
137 };
138
139 /*! @class wxObjcAutoRefFromAlloc
140 @templatefield T The type of _pointer_ (e.g. NSString*, NSRunLoop*)
141 @abstract Pointer-holder for Objective-C objects
142 @discussion
143 When constructing this object from a raw pointer, the pointer is assumed to have
144 come from an alloc-style method. That is, once you construct this object from
145 the pointer you must not balance your alloc with a call to release.
146
147 This class has been carefully designed to work with both the traditional Retain/Release
148 and the new Garbage Collected modes. In RR-mode it will prevent the object from being
149 released by managing the reference count using the retain/release semantics. In GC-mode
150 it will use a method (currently CFRetain/CFRelease) to ensure the object will never be
151 finalized until this object is destroyed.
152 */
153
154 template <class T>
155 class wxObjcAutoRefFromAlloc: wxObjcAutoRefBase
156 {
157 public:
158 wxObjcAutoRefFromAlloc(T p = 0)
159 : m_ptr(p)
160 // NOTE: this is from alloc. Do NOT retain
161 {
162 // CFRetain
163 // GC: Object is strongly retained and prevented from being collected
164 // non-GC: Simply realizes it's an Objective-C object and calls [p retain]
165 wxGCSafeRetain(p);
166 // ObjcRelease (e.g. [p release])
167 // GC: Objective-C retain/release mean nothing in GC mode
168 // non-GC: This is a normal release call, balancing the retain
169 ObjcRelease(static_cast<T>(p));
170 // The overall result:
171 // GC: Object is strongly retained
172 // non-GC: Retain count is the same as it was (retain then release)
173 }
174 wxObjcAutoRefFromAlloc(const wxObjcAutoRefFromAlloc& otherRef)
175 : m_ptr(otherRef.m_ptr)
176 { wxGCSafeRetain(m_ptr); }
177 ~wxObjcAutoRefFromAlloc()
178 { wxGCSafeRelease(m_ptr); }
179 wxObjcAutoRefFromAlloc& operator=(const wxObjcAutoRefFromAlloc& otherRef)
180 { wxGCSafeRetain(otherRef.m_ptr);
181 wxGCSafeRelease(m_ptr);
182 m_ptr = otherRef.m_ptr;
183 return *this;
184 }
185 operator T() const
186 { return static_cast<T>(m_ptr); }
187 T operator->() const
188 { return static_cast<T>(m_ptr); }
189 protected:
190 /*! @field m_ptr The pointer to the Objective-C object
191 @discussion
192 The pointer to the Objective-C object is typed as void* to avoid compiler-generated write
193 barriers as would be used for implicitly __strong object pointers and to avoid the similar
194 read barriers as would be used for an explicitly __weak object pointer. The write barriers
195 are useless unless this object is located in GC-managed heap which is highly unlikely.
196
197 Since we guarantee strong reference via CFRetain/CFRelease the write-barriers are not needed
198 at all, even if this object does happen to be allocated in GC-managed heap.
199 */
200 void *m_ptr;
201 };
202
203 /*!
204 @class wxObjcAutoRef
205 @description
206 A pointer holder that does retain its argument.
207 NOTE: It is suggest that you instead use wxObjcAutoRefFromAlloc<T> foo([aRawPointer retain])
208 */
209 template <class T>
210 class wxObjcAutoRef: public wxObjcAutoRefFromAlloc<T>
211 {
212 public:
213 /*! @method wxObjcAutoRef
214 @description
215 Uses the underlying wxObjcAutoRefFromAlloc and simply does a typical [p retain] such that
216 in RR-mode the object is in effectively the same retain-count state as it would have been
217 coming straight from an alloc method.
218 */
219 wxObjcAutoRef(T p = 0)
220 : wxObjcAutoRefFromAlloc<T>(p)
221 { // NOTE: ObjcRetain is correct because in GC-mode it balances ObjcRelease in our superclass constructor
222 // In RR mode it does retain and the superclass does retain/release thus resulting in an overall retain.
223 ObjcRetain(static_cast<T>(wxObjcAutoRefFromAlloc<T>::m_ptr));
224 }
225 ~wxObjcAutoRef() {}
226 wxObjcAutoRef(const wxObjcAutoRef& otherRef)
227 : wxObjcAutoRefFromAlloc<T>(otherRef)
228 {}
229 wxObjcAutoRef(const wxObjcAutoRefFromAlloc<T>& otherRef)
230 : wxObjcAutoRefFromAlloc<T>(otherRef)
231 {}
232 wxObjcAutoRef& operator=(const wxObjcAutoRef& otherRef)
233 { return wxObjcAutoRefFromAlloc<T>::operator=(otherRef); }
234 };
235
236 #endif //ndef _WX_COCOA_OBJCREF_H__