darling-objc4/ReleaseNotes.rtf

{\rtf1\mac\ansicpg10000\cocoartf824\cocoasubrtf420
{\fonttbl\f0\fswiss\fcharset77 Helvetica-Bold;\f1\fswiss\fcharset77 Helvetica;\f2\fnil\fcharset77 Monaco;
}
{\colortbl;\red255\green255\blue255;\red70\green130\blue100;}
\vieww11200\viewh14360\viewkind0
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs30 \cf0 Objective-C Release Notes\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0\fs24 \cf0 \
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b\fs30 \cf0 Mac OS X 10.5 Leopard
\f1\b0\fs24 \
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 Contents
\f1\b0 \
\'a5 Garbage Collection\
\'a5\'caProperties\
\'a5\'caLoading and Unloading Bundles\
\'a5 Method and Class Attributes\
\'a5\'ca@package Instance Variables\
\'a5\'caRuntime API changes\
\'a5\'ca64-bit ABI\
\'a5\'ca64-bit Class and Instance Variable Access Control\
\'a5\'ca64-bit Non-Fragile Instance Variables\
\'a5\'ca64-bit Zero-Cost C++-Compatible Exceptions\
\
\

\f0\b Garbage Collection\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 \
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).\
\
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.\
\
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.\
\
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.\
\
The compiler uses three "helper" functions for assignments of strong pointers to garbage collected memory into global memory (
\f2\fs20 objc_assign_global
\f1\fs24 ), garbage collected heap memory (
\f2\fs20 objc_assign_ivar
\f1\fs24 ), or into unknown memory (
\f2\fs20 objc_assign_strongCast
\f1\fs24 ).  For assignments of weak pointers it uses objc_assign_weak and for reads it uses objc_read_weak.\
\
When copying memory in bulk into a garbage collected block one must use the API 
\f2\fs20 objc_memmove_collectable(void *dst, const void *src, size_t size)
\f1\fs24 .\
\
Garbage Collection Errors\
\
The collector itself is found in
\f2\fs20  /usr/lib/libauto.dylib
\f1\fs24 . Its error messages are printed using 
\f2\fs20 malloc_printf
\f1\fs24 .  The ObjC runtime is found in 
\f2\fs20 /usr/lib/libobjc.dylib
\f1\fs24 .  Its errors are printed using 
\f2\fs20 _objc_inform
\f1\fs24 .  Currently we note resurrection and reference count underflow errors by calling the following routines:\
\
\pard\tx960\pardeftab960\ql\qnatural\pardirnatural

\f2\fs20 \cf2 \CocoaLigature0 objc_assign_global_error\
\pard\tx960\pardeftab960\ql\qnatural\pardirnatural
\cf0 objc_assign_ivar_error\
\pard\tx960\pardeftab960\ql\qnatural\pardirnatural
\cf2 objc_exception_during_finalize_error\
auto_zone_resurrection_error\cf0 \
\cf2 auto_refcount_underflow_error
\f1\fs24 \cf0 \CocoaLigature1 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 Properties
\f1\b0 \
\
The syntax for Objective-C properties has been overhauled since WWDC 2006. See the property documentation for details.\
\
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.\
\
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.\
\
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.\
\
Pointers may be held strongly under GC by declaring them __strong, and they can be zeroing weak by declaring them __weak.\
\
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.\
\
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.\
\
\

\f0\b Loading and Unloading Bundles\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 \
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.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 Method and Class Attributes\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\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:\
\
Deprecation and availability, including AvailabilityMacros.h\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f2\fs20 \cf0 	- (void)method:(id)param  __attribute__((deprecated));\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs24 \cf0 \
Unused parameters\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f2\fs20 \cf0 	- (void)method:(id) __attribute__((unused)) param;\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs24 \cf0 \
Sentinel parameters, including 
\f2\fs20 NS_REQUIRES_NIL_TERMINATION
\f1\fs24 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f2\fs20 \cf0 	- (void)methodWithObjects:(id)obj, ...  NS_REQUIRES_NIL_TERMINATION;\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs24 \cf0 \
Objective-C also supports some gcc attributes for Objective-C classes. Syntactically, attributes for a class precede the class's 
\f2\fs20 @interface
\f1\fs24  declaration. Supported attributes include:\
\
Deprecation and availability, including AvailabilityMacros.h\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f2\fs20 \cf0 	__attribute__((deprecated))\
	@interface MyDeprecatedClass : SomeSuperclass\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs24 \cf0 \
Visibility\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f2\fs20 \cf0 	__attribute__((visibility("hidden")))\
	@interface MyPrivateClass : SomeSuperclass
\f1\fs24 \
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 @package Instance Variables
\f1\b0 \
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f2\fs20 \cf0 @package
\f1\fs24  is a new ivar protection class, like 
\f2\fs20 @public
\f1\fs24  and 
\f2\fs20 @protected
\f1\fs24 . 
\f2\fs20 @package
\f1\fs24  ivars behave as follows:\
\'a5\'ca
\f2\fs20 @public
\f1\fs24  in 32-bit; \
\'a5\'ca
\f2\fs20 @public
\f1\fs24  in 64-bit, inside the framework that defined the class; \
\'a5\'ca
\f2\fs20 @private
\f1\fs24  in 64-bit, outside the framework that defined the class.\
\
In 64-bit, the ivar symbol for an 
\f2\fs20 @package
\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.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 Runtime API changes\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\b0 \cf0 The C interface to the Objective-C runtime (in 
\f2\fs20 <objc/*.h>
\f1\fs24 ) has changed significantly. Highlights include:\
\'a5\'caAlmost all structures are deprecated, including 
\f2\fs20 struct objc_class
\f1\fs24 . Functional replacements for most of these are provided.\
\'a5\'ca
\f2\fs20 class_poseAs
\f1\fs24  is deprecated. Use method list manipulation functions instead.\
\'a5\'ca
\f2\fs20 class_nextMethodList
\f1\fs24  is deprecated. Use 
\f2\fs20 class_copyMethodList
\f1\fs24  instead.\
\'a5\'ca
\f2\fs20 class_addMethods
\f1\fs24  is deprecated. Use 
\f2\fs20 class_addMethod
\f1\fs24  instead.\
\'a5\'ca
\f2\fs20 objc_addClass
\f1\fs24  is deprecated. Use 
\f2\fs20 objc_allocateClassPair
\f1\fs24  and 
\f2\fs20 objc_registerClassPair
\f1\fs24  instead.\
\'a5\'caIn general, all deprecated declarations are absent in 64-bit.\
\'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.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 64-bit ABI\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\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.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 64-bit Class and Instance Variable Access Control\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\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.\
\
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 
\f2\fs20 -fvisibility=hidden
\f1\fs24  or a linker export list may need to be changed.\
\
Class symbols have names of the form 
\f2\fs20 _OBJC_CLASS_$_ClassName
\f1\fs24  and 
\f2\fs20 _OBJC_METACLASS_$_ClassName
\f1\fs24  . The class symbol is used by clients who send messages to the class (i.e. 
\f2\fs20 [ClassName someMessage]
\f1\fs24 ). The metaclass symbol is used by clients who subclass the class.\
\
By default, class symbols are exported. They are affected by gcc's symbol visibility flags, so 
\f2\fs20 -fvisibility=hidden
\f1\fs24  will make the class symbols non-exported. The linker recognizes the old symbol name 
\f2\fs20 .objc_class_name_ClassName
\f1\fs24  in linker export lists and translates it to these symbols. \
\
Visibility of a single class can be changed using an attribute.\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f2\fs20 \cf0 	__attribute__((visibility("hidden")))\
	@interface ClassName : SomeSuperclass\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs24 \cf0 For classes with 
\f2\fs20 "default"
\f1\fs24  visibility, the class symbols are exported, and the ivar symbols are handled as described below. For classes with 
\f2\fs20 "hidden"
\f1\fs24  visibility, the class symbols and ivar symbols are all not exported.\
\
Ivar symbols have the form 
\f2\fs20 _OBJC_IVAR_$_ClassName.IvarName
\f1\fs24  . The ivar symbol is used by clients who read or write the ivar.\
\
By default, ivar symbols for 
\f2\fs20 @private
\f1\fs24  and 
\f2\fs20 @package
\f1\fs24  ivars are not exported, and ivar symbols for 
\f2\fs20 @public
\f1\fs24  and 
\f2\fs20 @protected
\f1\fs24  ivars are exported. This can be changed by export lists, 
\f2\fs20 -fvisibility
\f1\fs24 , or a visibility attribute on the class. Visibility attributes on individual ivars are currently not supported.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 64-bit Non-Fragile Instance Variables\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\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.\
\
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. \
\
Do not use 
\f2\fs20 @defs
\f1\fs24 . The ivar layout it presents cannot adapt to superclass changes.\
\
Do not use 
\f2\fs20 sizeof(SomeClass)
\f1\fs24 . Use 
\f2\fs20 class_getInstanceSize([SomeClass class])
\f1\fs24  instead.\
\
Do not use 
\f2\fs20 offsetof(SomeClass, SomeIvar)
\f1\fs24 . Use 
\f2\fs20 ivar_getOffset(class_getInstanceVariable([SomeClass class], "SomeIvar"))
\f1\fs24  instead.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\b \cf0 64-bit Zero-Cost C++-Compatible Exceptions\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\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++. \
\
"Zero-cost" try blocks incur no time penalty when entering an 
\f2\fs20 @try
\f1\fs24  block, unlike 32-bit which must call 
\f2\fs20 setjmp()
\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.\
\
The Cocoa frameworks require that all exceptions be instances of NSException or its subclasses. Do not throw objects of other types.\
\
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.\
\
In 64-bit, C++ exceptions and Objective-C exceptions are interoperable. In particular, C++ destructors and Objective-C 
\f2\fs20 @finally
\f1\fs24  blocks are honored when unwinding any exception, and default catch clauses - 
\f2\fs20 catch (...)
\f1\fs24  and 
\f2\fs20 @catch (...)
\f1\fs24  - are able to catch and re-throw any exception.\
\
Objective-C 
\f2\fs20 @catch (id e)
\f1\fs24  catches any Objective-C exception, but no C++ exceptions. Use 
\f2\fs20 @catch (...)
\f1\fs24  to catch everything, and 
\f2\fs20 @throw;
\f1\fs24  to re-throw caught exceptions. 
\f2\fs20 @catch (...)
\f1\fs24  is allowed in 32-bit, and has the same effect there as 
\f2\fs20 @catch (id e)
\f1\fs24 . \
}