ReleaseNotes.rtf

   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 \
  39 The 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 \
  41 The 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 \
  43 The 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 \
  45 A 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 \
  47 The 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 \
  55 When 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 \
  59 Garbage Collection Errors\
  60 \
  61 The 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\
  78 auto_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 \
  89 The syntax for Objective-C properties has been overhauled since WWDC 2006. See the property documentation for details.\
  90 \
  91 In 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 \
  93 By 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 \
  95 Access 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 \
  97 Pointers may be held strongly under GC by declaring them __strong, and they can be zeroing weak by declaring them __weak.\
  98 \
  99 The 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 \
 101 In 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 \
 109 Since 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 \
 120 Deprecation 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 \
 127 Unused 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 \
 134 Sentinel 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 \
 143 Objective-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 \
 147 Deprecation 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 \
 155 Visibility\
 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 \
 188 In 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 \
 246 The 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 \
 250 Class 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 \
 258 By 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 \
 264 Visibility 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 \
 277 Ivar 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 \
 281 By 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 \
 302 Ivars 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 \
 304 Do not use
 305 \f2\fs20 @defs
 306 \f1\fs24 . The ivar layout it presents cannot adapt to superclass changes.\
 307 \
 308 Do not use
 309 \f2\fs20 sizeof(SomeClass)
 310 \f1\fs24 . Use
 311 \f2\fs20 class_getInstanceSize([SomeClass class])
 312 \f1\fs24  instead.\
 313 \
 314 Do 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 \
 335 The Cocoa frameworks require that all exceptions be instances of NSException or its subclasses. Do not throw objects of other types.\
 336 \
 337 The 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 \
 339 In 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 \
 347 Objective-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 }