1{\rtf1\mac\ansicpg10000\cocoartf824\cocoasubrtf420
2{\fonttbl\f0\fswiss\fcharset77 Helvetica-Bold;\f1\fswiss\fcharset77 Helvetica;\f2\fnil\fcharset77 Monaco;
3}
4{\colortbl;\red255\green255\blue255;\red70\green130\blue100;}
5\vieww11200\viewh14360\viewkind0
6\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
7
8\f0\b\fs30 \cf0 Objective-C Release Notes\
9\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
10
11\f1\b0\fs24 \cf0 \
12\
13\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
14
15\f0\b\fs30 \cf0 Mac OS X 10.5 Leopard
16\f1\b0\fs24 \
17\
18\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
19
20\f0\b \cf0 Contents
21\f1\b0 \
22\'a5 Garbage Collection\
23\'a5\'caProperties\
24\'a5\'caLoading and Unloading Bundles\
25\'a5 Method and Class Attributes\
26\'a5\'ca@package Instance Variables\
27\'a5\'caRuntime API changes\
28\'a5\'ca64-bit ABI\
29\'a5\'ca64-bit Class and Instance Variable Access Control\
30\'a5\'ca64-bit Non-Fragile Instance Variables\
31\'a5\'ca64-bit Zero-Cost C++-Compatible Exceptions\
32\
33\
34
35\f0\b Garbage Collection\
36\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
37
38\f1\b0 \cf0 \
39The Objective-C runtime examines on startup the execution image to determine whether to run with garbage collection or not.  Each object file has an info section and they must all agree for execution to proceed.  Standard compilation results in an info section that indicates that no GC capability is present.  Compiling with -fobjc-gc indicates that both GC and retain/release logic is present.  Compiling with -fobjc-gc-only indicates that only GC logic is present.  A non-GC executable that attempts to load a gc-only framework will fail, as will a GC capable executable that attemps to load a GC incapable framework (or bundle).\
40\
41The collector initially runs only on the main thread when requested via objc_collect_if_needed(1), which is called automatically from the autoreleasepool -drain method.  The AppKit arranges to call objc_start_collector_thread() after launch and subsequently collections run on a dedicated thread and are responsive to pure allocation demand.  The objc_set_collection_threshold and objc_set_collection_ratio calls are used to establish the "need" for a collection.  Once every ratio times a full (complete) collection will occur; otherwise a generational collection will be done if allocations have exceeded the threshold.\
42\
43The garbage collector minimally pauses those threads which have been registered to it while collecting.        Registration occurs during establishment of an NSThread, not simply a pthread.\
44\
45A critical assumption that the collector makes is that one thread never gains access to an object (or more generally any block of garbage collected memory) by way of a pointer to another thread's stack memory.    In other words, the collector does not make provision for cross thread stack references.  This enables the collector to avoid pausing all threads at the same time while it examines recursively all of their references.\
46\
47The compiler uses three "helper" functions for assignments of strong pointers to garbage collected memory into global memory (
48\f2\fs20 objc_assign_global
49\f1\fs24 ), garbage collected heap memory (
50\f2\fs20 objc_assign_ivar
51\f1\fs24 ), or into unknown memory (
52\f2\fs20 objc_assign_strongCast
53\f1\fs24 ).  For assignments of weak pointers it uses objc_assign_weak and for reads it uses objc_read_weak.\
54\
55When copying memory in bulk into a garbage collected block one must use the API 
56\f2\fs20 objc_memmove_collectable(void *dst, const void *src, size_t size)
57\f1\fs24 .\
58\
59Garbage Collection Errors\
60\
61The collector itself is found in
62\f2\fs20  /usr/lib/libauto.dylib
63\f1\fs24 . Its error messages are printed using 
64\f2\fs20 malloc_printf
65\f1\fs24 .  The ObjC runtime is found in 
66\f2\fs20 /usr/lib/libobjc.dylib
67\f1\fs24 .  Its errors are printed using 
68\f2\fs20 _objc_inform
69\f1\fs24 .  Currently we note resurrection and reference count underflow errors by calling the following routines:\
70\
71\pard\tx960\pardeftab960\ql\qnatural\pardirnatural
72
73\f2\fs20 \cf2 \CocoaLigature0 objc_assign_global_error\
74\pard\tx960\pardeftab960\ql\qnatural\pardirnatural
75\cf0 objc_assign_ivar_error\
76\pard\tx960\pardeftab960\ql\qnatural\pardirnatural
77\cf2 objc_exception_during_finalize_error\
78auto_zone_resurrection_error\cf0 \
79\cf2 auto_refcount_underflow_error
80\f1\fs24 \cf0 \CocoaLigature1 \
81\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
82\cf0 \
83\
84\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
85
86\f0\b \cf0 Properties
87\f1\b0 \
88\
89The syntax for Objective-C properties has been overhauled since WWDC 2006. See the property documentation for details.\
90\
91In summary, @property(attributes) type name introduces an implicit declaration of a "getter" and a "setter" method (unless a read-only property is requested) for the "variable" named. The setter= and getter= attributes allow one to specify the names of the methods, otherwise a "name" method and a "setName:" method are implicitly declared.  They may also be explicitly named.\
92\
93By default, properties are assigned when set.  For objects under non-GC this is often incorrect and a warning is issued unless the assignment semantic is explicitly named.  There are three choices - assign, for non-retained object references, copy, for objects that are copied and implicitly retained, and simply retain, for objects that require being retained when set.\
94\
95Access to properties is atomic by default.  This is trivial under GC for almost everything and also trivial under non-GC for everything but objects and structures.  In particular atomic access to retained objects under non-GC conditions can be expensive. As such, a nonatomic property attribute is available.\
96\
97Pointers may be held strongly under GC by declaring them __strong, and they can be zeroing weak by declaring them __weak.\
98\
99The implementations for properties can be provided by the compiler and runtime through the use of the @synthesize statement in the @implementation section of the class (or class extension).  The compiler expects an instance variable of the same name as the property.  If one wishes a different name it can be supplied to the @synthesize statement.\
100\
101In particular the compiler and runtime will implement accessors to retained objects by using atomic compare and swap instructions.  It is extremely dangerous to directly access an atomic object property through its instance variable since another thread might change its value unpredictably.  As such the compiler will warn you about such unprotected accesses.  The runtime, in fact, will temporarily use the least significant bit of the instance variable as a temporary lock while retaining the new value and releasing the old.  Direct use of an atomic instance variable under non-GC is strongly discouraged.\
102\
103\
104
105\f0\b Loading and Unloading Bundles\
106\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
107
108\f1\b0 \cf0 \
109Since Mac OS X Version 10.4 it has been possible to unload bundles containing Objective-C.  No attempt is made to prevent this if objects are still present for classes that are unloaded.  Subclasses of classes loaded in bundles are particularly vulnerable.\
110\
111\
112\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
113
114\f0\b \cf0 Method and Class Attributes\
115\
116\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
117
118\f1\b0 \cf0 Objective-C now supports some gcc attributes for Objective-C methods. Syntactically, attributes for a method follow the method's declaration, and attributes for a method parameter sit between the parameter type and the parameter name. Supported attributes include:\
119\
120Deprecation and availability, including AvailabilityMacros.h\
121\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
122
123\f2\fs20 \cf0 	- (void)method:(id)param  __attribute__((deprecated));\
124\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
125
126\f1\fs24 \cf0 \
127Unused parameters\
128\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
129
130\f2\fs20 \cf0 	- (void)method:(id) __attribute__((unused)) param;\
131\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
132
133\f1\fs24 \cf0 \
134Sentinel parameters, including 
135\f2\fs20 NS_REQUIRES_NIL_TERMINATION
136\f1\fs24 \
137\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
138
139\f2\fs20 \cf0 	- (void)methodWithObjects:(id)obj, ...  NS_REQUIRES_NIL_TERMINATION;\
140\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
141
142\f1\fs24 \cf0 \
143Objective-C also supports some gcc attributes for Objective-C classes. Syntactically, attributes for a class precede the class's 
144\f2\fs20 @interface
145\f1\fs24  declaration. Supported attributes include:\
146\
147Deprecation and availability, including AvailabilityMacros.h\
148\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
149
150\f2\fs20 \cf0 	__attribute__((deprecated))\
151	@interface MyDeprecatedClass : SomeSuperclass\
152\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
153
154\f1\fs24 \cf0 \
155Visibility\
156\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
157
158\f2\fs20 \cf0 	__attribute__((visibility("hidden")))\
159	@interface MyPrivateClass : SomeSuperclass
160\f1\fs24 \
161\
162\
163\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
164
165\f0\b \cf0 @package Instance Variables
166\f1\b0 \
167\
168\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
169
170\f2\fs20 \cf0 @package
171\f1\fs24  is a new ivar protection class, like 
172\f2\fs20 @public
173\f1\fs24  and 
174\f2\fs20 @protected
175\f1\fs24 . 
176\f2\fs20 @package
177\f1\fs24  ivars behave as follows:\
178\'a5\'ca
179\f2\fs20 @public
180\f1\fs24  in 32-bit; \
181\'a5\'ca
182\f2\fs20 @public
183\f1\fs24  in 64-bit, inside the framework that defined the class; \
184\'a5\'ca
185\f2\fs20 @private
186\f1\fs24  in 64-bit, outside the framework that defined the class.\
187\
188In 64-bit, the ivar symbol for an 
189\f2\fs20 @package
190\f1\fs24  ivar is not exported, so any attempt to use the ivar from outside the framework that defined the class will fail with a link error. See "64-bit Class and Instance Variable Access Control" for more about ivar symbols.\
191\
192\
193\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
194
195\f0\b \cf0 Runtime API changes\
196\
197\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
198
199\f1\b0 \cf0 The C interface to the Objective-C runtime (in 
200\f2\fs20 <objc/*.h>
201\f1\fs24 ) has changed significantly. Highlights include:\
202\'a5\'caAlmost all structures are deprecated, including 
203\f2\fs20 struct objc_class
204\f1\fs24 . Functional replacements for most of these are provided.\
205\'a5\'ca
206\f2\fs20 class_poseAs
207\f1\fs24  is deprecated. Use method list manipulation functions instead.\
208\'a5\'ca
209\f2\fs20 class_nextMethodList
210\f1\fs24  is deprecated. Use 
211\f2\fs20 class_copyMethodList
212\f1\fs24  instead.\
213\'a5\'ca
214\f2\fs20 class_addMethods
215\f1\fs24  is deprecated. Use 
216\f2\fs20 class_addMethod
217\f1\fs24  instead.\
218\'a5\'ca
219\f2\fs20 objc_addClass
220\f1\fs24  is deprecated. Use 
221\f2\fs20 objc_allocateClassPair
222\f1\fs24  and 
223\f2\fs20 objc_registerClassPair
224\f1\fs24  instead.\
225\'a5\'caIn general, all deprecated declarations are absent in 64-bit.\
226\'a5\'caThe API in objc/objc-runtime.h and objc/objc-class.h is now in objc/runtime.h and objc/message.h. The old header files simply #include the new ones.\
227\
228\
229\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
230
231\f0\b \cf0 64-bit ABI\
232\
233\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
234
235\f1\b0 \cf0 The 64-bit Objective-C ABI is generally unlike the 32-bit ABI. The new ABI provides new features, better performance, and improved future adaptability. All aspects of the 64-bit ABI are private and subject to future change. Forthcoming documentation will describe the ABI for the use of compilers and developer tools only.\
236\
237\
238\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
239
240\f0\b \cf0 64-bit Class and Instance Variable Access Control\
241\
242\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
243
244\f1\b0 \cf0 In 64-bit Objective-C, access control for classes and each class and instance variable has a symbol associated with it. All uses of a class or instance variable reference this symbol. These symbols are subject to access control by the linker.\
245\
246The upshot is that access to private classes and ivars is more strictly enforced. Illegal use of a private ivar may fail with a link error. Frameworks that provide classes and ivars must correctly export their symbols. In particular, frameworks built with 
247\f2\fs20 -fvisibility=hidden
248\f1\fs24  or a linker export list may need to be changed.\
249\
250Class symbols have names of the form 
251\f2\fs20 _OBJC_CLASS_$_ClassName
252\f1\fs24  and 
253\f2\fs20 _OBJC_METACLASS_$_ClassName
254\f1\fs24  . The class symbol is used by clients who send messages to the class (i.e. 
255\f2\fs20 [ClassName someMessage]
256\f1\fs24 ). The metaclass symbol is used by clients who subclass the class.\
257\
258By default, class symbols are exported. They are affected by gcc's symbol visibility flags, so 
259\f2\fs20 -fvisibility=hidden
260\f1\fs24  will make the class symbols non-exported. The linker recognizes the old symbol name 
261\f2\fs20 .objc_class_name_ClassName
262\f1\fs24  in linker export lists and translates it to these symbols. \
263\
264Visibility of a single class can be changed using an attribute.\
265\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
266
267\f2\fs20 \cf0 	__attribute__((visibility("hidden")))\
268	@interface ClassName : SomeSuperclass\
269\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
270
271\f1\fs24 \cf0 For classes with 
272\f2\fs20 "default"
273\f1\fs24  visibility, the class symbols are exported, and the ivar symbols are handled as described below. For classes with 
274\f2\fs20 "hidden"
275\f1\fs24  visibility, the class symbols and ivar symbols are all not exported.\
276\
277Ivar symbols have the form 
278\f2\fs20 _OBJC_IVAR_$_ClassName.IvarName
279\f1\fs24  . The ivar symbol is used by clients who read or write the ivar.\
280\
281By default, ivar symbols for 
282\f2\fs20 @private
283\f1\fs24  and 
284\f2\fs20 @package
285\f1\fs24  ivars are not exported, and ivar symbols for 
286\f2\fs20 @public
287\f1\fs24  and 
288\f2\fs20 @protected
289\f1\fs24  ivars are exported. This can be changed by export lists, 
290\f2\fs20 -fvisibility
291\f1\fs24 , or a visibility attribute on the class. Visibility attributes on individual ivars are currently not supported.\
292\
293\
294\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
295
296\f0\b \cf0 64-bit Non-Fragile Instance Variables\
297\
298\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
299
300\f1\b0 \cf0 All instance variables in 64-bit Objective-C are non-fragile. That is, existing compiled code that uses a class's ivars will not break when the class or a superclass changes its own ivar layout. In particular, framework classes may add new ivars without breaking subclasses compiled against a previous version of the framework.\
301\
302Ivars may be added or reordered freely; existing users of a reordered ivar will adapt transparently. Other ivar changes are safe except that they will break any existing users of the ivar: deleting an ivar, renaming an ivar, moving an ivar to a different class, and changing the type of an ivar. \
303\
304Do not use 
305\f2\fs20 @defs
306\f1\fs24 . The ivar layout it presents cannot adapt to superclass changes.\
307\
308Do not use 
309\f2\fs20 sizeof(SomeClass)
310\f1\fs24 . Use 
311\f2\fs20 class_getInstanceSize([SomeClass class])
312\f1\fs24  instead.\
313\
314Do not use 
315\f2\fs20 offsetof(SomeClass, SomeIvar)
316\f1\fs24 . Use 
317\f2\fs20 ivar_getOffset(class_getInstanceVariable([SomeClass class], "SomeIvar"))
318\f1\fs24  instead.\
319\
320\
321\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
322
323\f0\b \cf0 64-bit Zero-Cost C++-Compatible Exceptions\
324\
325\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
326
327\f1\b0 \cf0 In 64-bit, the implementation of Objective-C exceptions has been rewritten. The new system provides "zero-cost" try blocks and interoperability with C++. \
328\
329"Zero-cost" try blocks incur no time penalty when entering an 
330\f2\fs20 @try
331\f1\fs24  block, unlike 32-bit which must call 
332\f2\fs20 setjmp()
333\f1\fs24  and other additional bookkeeping. On the other hand, actually throwing an exception is much more expensive. For best performance in 64-bit, exceptions should be thrown only in exceptional cases.\
334\
335The Cocoa frameworks require that all exceptions be instances of NSException or its subclasses. Do not throw objects of other types.\
336\
337The Cocoa frameworks are generally not exception-safe. Their general pattern is that exceptions are reserved for programmer error only, and the program should quit soon after catching such an exception. Be careful when throwing exceptions across the Cocoa frameworks.\
338\
339In 64-bit, C++ exceptions and Objective-C exceptions are interoperable. In particular, C++ destructors and Objective-C 
340\f2\fs20 @finally
341\f1\fs24  blocks are honored when unwinding any exception, and default catch clauses - 
342\f2\fs20 catch (...)
343\f1\fs24  and 
344\f2\fs20 @catch (...)
345\f1\fs24  - are able to catch and re-throw any exception.\
346\
347Objective-C 
348\f2\fs20 @catch (id e)
349\f1\fs24  catches any Objective-C exception, but no C++ exceptions. Use 
350\f2\fs20 @catch (...)
351\f1\fs24  to catch everything, and 
352\f2\fs20 @throw;
353\f1\fs24  to re-throw caught exceptions. 
354\f2\fs20 @catch (...)
355\f1\fs24  is allowed in 32-bit, and has the same effect there as 
356\f2\fs20 @catch (id e)
357\f1\fs24 . \
358}