1*ec02198aSmrg@c Copyright (C) 1988-2020 Free Software Foundation, Inc. 210d565efSmrg@c This is part of the GCC manual. 310d565efSmrg@c For copying conditions, see the file gcc.texi. 410d565efSmrg 510d565efSmrg@node Objective-C 610d565efSmrg@comment node-name, next, previous, up 710d565efSmrg 810d565efSmrg@chapter GNU Objective-C Features 910d565efSmrg 1010d565efSmrgThis document is meant to describe some of the GNU Objective-C 1110d565efSmrgfeatures. It is not intended to teach you Objective-C. There are 1210d565efSmrgseveral resources on the Internet that present the language. 1310d565efSmrg 1410d565efSmrg@menu 1510d565efSmrg* GNU Objective-C runtime API:: 1610d565efSmrg* Executing code before main:: 1710d565efSmrg* Type encoding:: 1810d565efSmrg* Garbage Collection:: 1910d565efSmrg* Constant string objects:: 2010d565efSmrg* compatibility_alias:: 2110d565efSmrg* Exceptions:: 2210d565efSmrg* Synchronization:: 2310d565efSmrg* Fast enumeration:: 2410d565efSmrg* Messaging with the GNU Objective-C runtime:: 2510d565efSmrg@end menu 2610d565efSmrg 2710d565efSmrg@c ========================================================================= 2810d565efSmrg@node GNU Objective-C runtime API 2910d565efSmrg@section GNU Objective-C Runtime API 3010d565efSmrg 3110d565efSmrgThis section is specific for the GNU Objective-C runtime. If you are 3210d565efSmrgusing a different runtime, you can skip it. 3310d565efSmrg 3410d565efSmrgThe GNU Objective-C runtime provides an API that allows you to 3510d565efSmrginteract with the Objective-C runtime system, querying the live 3610d565efSmrgruntime structures and even manipulating them. This allows you for 3710d565efSmrgexample to inspect and navigate classes, methods and protocols; to 3810d565efSmrgdefine new classes or new methods, and even to modify existing classes 3910d565efSmrgor protocols. 4010d565efSmrg 4110d565efSmrgIf you are using a ``Foundation'' library such as GNUstep-Base, this 4210d565efSmrglibrary will provide you with a rich set of functionality to do most 4310d565efSmrgof the inspection tasks, and you probably will only need direct access 4410d565efSmrgto the GNU Objective-C runtime API to define new classes or methods. 4510d565efSmrg 4610d565efSmrg@menu 4710d565efSmrg* Modern GNU Objective-C runtime API:: 4810d565efSmrg* Traditional GNU Objective-C runtime API:: 4910d565efSmrg@end menu 5010d565efSmrg 5110d565efSmrg@c ========================================================================= 5210d565efSmrg@node Modern GNU Objective-C runtime API 5310d565efSmrg@subsection Modern GNU Objective-C Runtime API 5410d565efSmrg 5510d565efSmrgThe GNU Objective-C runtime provides an API which is similar to the 5610d565efSmrgone provided by the ``Objective-C 2.0'' Apple/NeXT Objective-C 5710d565efSmrgruntime. The API is documented in the public header files of the GNU 5810d565efSmrgObjective-C runtime: 5910d565efSmrg 6010d565efSmrg@itemize @bullet 6110d565efSmrg 6210d565efSmrg@item 6310d565efSmrg@file{objc/objc.h}: this is the basic Objective-C header file, 6410d565efSmrgdefining the basic Objective-C types such as @code{id}, @code{Class} 6510d565efSmrgand @code{BOOL}. You have to include this header to do almost 6610d565efSmrganything with Objective-C. 6710d565efSmrg 6810d565efSmrg@item 6910d565efSmrg@file{objc/runtime.h}: this header declares most of the public runtime 7010d565efSmrgAPI functions allowing you to inspect and manipulate the Objective-C 7110d565efSmrgruntime data structures. These functions are fairly standardized 7210d565efSmrgacross Objective-C runtimes and are almost identical to the Apple/NeXT 7310d565efSmrgObjective-C runtime ones. It does not declare functions in some 7410d565efSmrgspecialized areas (constructing and forwarding message invocations, 7510d565efSmrgthreading) which are in the other headers below. You have to include 7610d565efSmrg@file{objc/objc.h} and @file{objc/runtime.h} to use any of the 7710d565efSmrgfunctions, such as @code{class_getName()}, declared in 7810d565efSmrg@file{objc/runtime.h}. 7910d565efSmrg 8010d565efSmrg@item 8110d565efSmrg@file{objc/message.h}: this header declares public functions used to 8210d565efSmrgconstruct, deconstruct and forward message invocations. Because 8310d565efSmrgmessaging is done in quite a different way on different runtimes, 8410d565efSmrgfunctions in this header are specific to the GNU Objective-C runtime 8510d565efSmrgimplementation. 8610d565efSmrg 8710d565efSmrg@item 8810d565efSmrg@file{objc/objc-exception.h}: this header declares some public 8910d565efSmrgfunctions related to Objective-C exceptions. For example functions in 9010d565efSmrgthis header allow you to throw an Objective-C exception from plain 9110d565efSmrgC/C++ code. 9210d565efSmrg 9310d565efSmrg@item 9410d565efSmrg@file{objc/objc-sync.h}: this header declares some public functions 9510d565efSmrgrelated to the Objective-C @code{@@synchronized()} syntax, allowing 9610d565efSmrgyou to emulate an Objective-C @code{@@synchronized()} block in plain 9710d565efSmrgC/C++ code. 9810d565efSmrg 9910d565efSmrg@item 10010d565efSmrg@file{objc/thr.h}: this header declares a public runtime API threading 10110d565efSmrglayer that is only provided by the GNU Objective-C runtime. It 10210d565efSmrgdeclares functions such as @code{objc_mutex_lock()}, which provide a 10310d565efSmrgplatform-independent set of threading functions. 10410d565efSmrg 10510d565efSmrg@end itemize 10610d565efSmrg 10710d565efSmrgThe header files contain detailed documentation for each function in 10810d565efSmrgthe GNU Objective-C runtime API. 10910d565efSmrg 11010d565efSmrg@c ========================================================================= 11110d565efSmrg@node Traditional GNU Objective-C runtime API 11210d565efSmrg@subsection Traditional GNU Objective-C Runtime API 11310d565efSmrg 11410d565efSmrgThe GNU Objective-C runtime used to provide a different API, which we 11510d565efSmrgcall the ``traditional'' GNU Objective-C runtime API. Functions 11610d565efSmrgbelonging to this API are easy to recognize because they use a 11710d565efSmrgdifferent naming convention, such as @code{class_get_super_class()} 11810d565efSmrg(traditional API) instead of @code{class_getSuperclass()} (modern 11910d565efSmrgAPI). Software using this API includes the file 12010d565efSmrg@file{objc/objc-api.h} where it is declared. 12110d565efSmrg 12210d565efSmrgStarting with GCC 4.7.0, the traditional GNU runtime API is no longer 12310d565efSmrgavailable. 12410d565efSmrg 12510d565efSmrg@c ========================================================================= 12610d565efSmrg@node Executing code before main 12710d565efSmrg@section @code{+load}: Executing Code before @code{main} 12810d565efSmrg 12910d565efSmrgThis section is specific for the GNU Objective-C runtime. If you are 13010d565efSmrgusing a different runtime, you can skip it. 13110d565efSmrg 13210d565efSmrgThe GNU Objective-C runtime provides a way that allows you to execute 13310d565efSmrgcode before the execution of the program enters the @code{main} 13410d565efSmrgfunction. The code is executed on a per-class and a per-category basis, 13510d565efSmrgthrough a special class method @code{+load}. 13610d565efSmrg 13710d565efSmrgThis facility is very useful if you want to initialize global variables 13810d565efSmrgwhich can be accessed by the program directly, without sending a message 13910d565efSmrgto the class first. The usual way to initialize global variables, in the 14010d565efSmrg@code{+initialize} method, might not be useful because 14110d565efSmrg@code{+initialize} is only called when the first message is sent to a 14210d565efSmrgclass object, which in some cases could be too late. 14310d565efSmrg 14410d565efSmrgSuppose for example you have a @code{FileStream} class that declares 14510d565efSmrg@code{Stdin}, @code{Stdout} and @code{Stderr} as global variables, like 14610d565efSmrgbelow: 14710d565efSmrg 14810d565efSmrg@smallexample 14910d565efSmrg 15010d565efSmrgFileStream *Stdin = nil; 15110d565efSmrgFileStream *Stdout = nil; 15210d565efSmrgFileStream *Stderr = nil; 15310d565efSmrg 15410d565efSmrg@@implementation FileStream 15510d565efSmrg 15610d565efSmrg+ (void)initialize 15710d565efSmrg@{ 15810d565efSmrg Stdin = [[FileStream new] initWithFd:0]; 15910d565efSmrg Stdout = [[FileStream new] initWithFd:1]; 16010d565efSmrg Stderr = [[FileStream new] initWithFd:2]; 16110d565efSmrg@} 16210d565efSmrg 16310d565efSmrg/* @r{Other methods here} */ 16410d565efSmrg@@end 16510d565efSmrg 16610d565efSmrg@end smallexample 16710d565efSmrg 16810d565efSmrgIn this example, the initialization of @code{Stdin}, @code{Stdout} and 16910d565efSmrg@code{Stderr} in @code{+initialize} occurs too late. The programmer can 17010d565efSmrgsend a message to one of these objects before the variables are actually 17110d565efSmrginitialized, thus sending messages to the @code{nil} object. The 17210d565efSmrg@code{+initialize} method which actually initializes the global 17310d565efSmrgvariables is not invoked until the first message is sent to the class 17410d565efSmrgobject. The solution would require these variables to be initialized 17510d565efSmrgjust before entering @code{main}. 17610d565efSmrg 17710d565efSmrgThe correct solution of the above problem is to use the @code{+load} 17810d565efSmrgmethod instead of @code{+initialize}: 17910d565efSmrg 18010d565efSmrg@smallexample 18110d565efSmrg 18210d565efSmrg@@implementation FileStream 18310d565efSmrg 18410d565efSmrg+ (void)load 18510d565efSmrg@{ 18610d565efSmrg Stdin = [[FileStream new] initWithFd:0]; 18710d565efSmrg Stdout = [[FileStream new] initWithFd:1]; 18810d565efSmrg Stderr = [[FileStream new] initWithFd:2]; 18910d565efSmrg@} 19010d565efSmrg 19110d565efSmrg/* @r{Other methods here} */ 19210d565efSmrg@@end 19310d565efSmrg 19410d565efSmrg@end smallexample 19510d565efSmrg 19610d565efSmrgThe @code{+load} is a method that is not overridden by categories. If a 19710d565efSmrgclass and a category of it both implement @code{+load}, both methods are 19810d565efSmrginvoked. This allows some additional initializations to be performed in 19910d565efSmrga category. 20010d565efSmrg 20110d565efSmrgThis mechanism is not intended to be a replacement for @code{+initialize}. 20210d565efSmrgYou should be aware of its limitations when you decide to use it 20310d565efSmrginstead of @code{+initialize}. 20410d565efSmrg 20510d565efSmrg@menu 20610d565efSmrg* What you can and what you cannot do in +load:: 20710d565efSmrg@end menu 20810d565efSmrg 20910d565efSmrg 21010d565efSmrg@node What you can and what you cannot do in +load 21110d565efSmrg@subsection What You Can and Cannot Do in @code{+load} 21210d565efSmrg 21310d565efSmrg@code{+load} is to be used only as a last resort. Because it is 21410d565efSmrgexecuted very early, most of the Objective-C runtime machinery will 21510d565efSmrgnot be ready when @code{+load} is executed; hence @code{+load} works 21610d565efSmrgbest for executing C code that is independent on the Objective-C 21710d565efSmrgruntime. 21810d565efSmrg 21910d565efSmrgThe @code{+load} implementation in the GNU runtime guarantees you the 22010d565efSmrgfollowing things: 22110d565efSmrg 22210d565efSmrg@itemize @bullet 22310d565efSmrg 22410d565efSmrg@item 22510d565efSmrgyou can write whatever C code you like; 22610d565efSmrg 22710d565efSmrg@item 22810d565efSmrgyou can allocate and send messages to objects whose class is implemented 22910d565efSmrgin the same file; 23010d565efSmrg 23110d565efSmrg@item 23210d565efSmrgthe @code{+load} implementation of all super classes of a class are 23310d565efSmrgexecuted before the @code{+load} of that class is executed; 23410d565efSmrg 23510d565efSmrg@item 23610d565efSmrgthe @code{+load} implementation of a class is executed before the 23710d565efSmrg@code{+load} implementation of any category. 23810d565efSmrg 23910d565efSmrg@end itemize 24010d565efSmrg 24110d565efSmrgIn particular, the following things, even if they can work in a 24210d565efSmrgparticular case, are not guaranteed: 24310d565efSmrg 24410d565efSmrg@itemize @bullet 24510d565efSmrg 24610d565efSmrg@item 24710d565efSmrgallocation of or sending messages to arbitrary objects; 24810d565efSmrg 24910d565efSmrg@item 25010d565efSmrgallocation of or sending messages to objects whose classes have a 25110d565efSmrgcategory implemented in the same file; 25210d565efSmrg 25310d565efSmrg@item 25410d565efSmrgsending messages to Objective-C constant strings (@code{@@"this is a 25510d565efSmrgconstant string"}); 25610d565efSmrg 25710d565efSmrg@end itemize 25810d565efSmrg 25910d565efSmrgYou should make no assumptions about receiving @code{+load} in sibling 26010d565efSmrgclasses when you write @code{+load} of a class. The order in which 26110d565efSmrgsibling classes receive @code{+load} is not guaranteed. 26210d565efSmrg 26310d565efSmrgThe order in which @code{+load} and @code{+initialize} are called could 26410d565efSmrgbe problematic if this matters. If you don't allocate objects inside 26510d565efSmrg@code{+load}, it is guaranteed that @code{+load} is called before 26610d565efSmrg@code{+initialize}. If you create an object inside @code{+load} the 26710d565efSmrg@code{+initialize} method of object's class is invoked even if 26810d565efSmrg@code{+load} was not invoked. Note if you explicitly call @code{+load} 26910d565efSmrgon a class, @code{+initialize} will be called first. To avoid possible 27010d565efSmrgproblems try to implement only one of these methods. 27110d565efSmrg 27210d565efSmrgThe @code{+load} method is also invoked when a bundle is dynamically 27310d565efSmrgloaded into your running program. This happens automatically without any 27410d565efSmrgintervening operation from you. When you write bundles and you need to 27510d565efSmrgwrite @code{+load} you can safely create and send messages to objects whose 27610d565efSmrgclasses already exist in the running program. The same restrictions as 27710d565efSmrgabove apply to classes defined in bundle. 27810d565efSmrg 27910d565efSmrg 28010d565efSmrg 28110d565efSmrg@node Type encoding 28210d565efSmrg@section Type Encoding 28310d565efSmrg 28410d565efSmrgThis is an advanced section. Type encodings are used extensively by 28510d565efSmrgthe compiler and by the runtime, but you generally do not need to know 28610d565efSmrgabout them to use Objective-C. 28710d565efSmrg 28810d565efSmrgThe Objective-C compiler generates type encodings for all the types. 28910d565efSmrgThese type encodings are used at runtime to find out information about 29010d565efSmrgselectors and methods and about objects and classes. 29110d565efSmrg 29210d565efSmrgThe types are encoded in the following way: 29310d565efSmrg 29410d565efSmrg@c @sp 1 29510d565efSmrg 29610d565efSmrg@multitable @columnfractions .25 .75 29710d565efSmrg@item @code{_Bool} 29810d565efSmrg@tab @code{B} 29910d565efSmrg@item @code{char} 30010d565efSmrg@tab @code{c} 30110d565efSmrg@item @code{unsigned char} 30210d565efSmrg@tab @code{C} 30310d565efSmrg@item @code{short} 30410d565efSmrg@tab @code{s} 30510d565efSmrg@item @code{unsigned short} 30610d565efSmrg@tab @code{S} 30710d565efSmrg@item @code{int} 30810d565efSmrg@tab @code{i} 30910d565efSmrg@item @code{unsigned int} 31010d565efSmrg@tab @code{I} 31110d565efSmrg@item @code{long} 31210d565efSmrg@tab @code{l} 31310d565efSmrg@item @code{unsigned long} 31410d565efSmrg@tab @code{L} 31510d565efSmrg@item @code{long long} 31610d565efSmrg@tab @code{q} 31710d565efSmrg@item @code{unsigned long long} 31810d565efSmrg@tab @code{Q} 31910d565efSmrg@item @code{float} 32010d565efSmrg@tab @code{f} 32110d565efSmrg@item @code{double} 32210d565efSmrg@tab @code{d} 32310d565efSmrg@item @code{long double} 32410d565efSmrg@tab @code{D} 32510d565efSmrg@item @code{void} 32610d565efSmrg@tab @code{v} 32710d565efSmrg@item @code{id} 32810d565efSmrg@tab @code{@@} 32910d565efSmrg@item @code{Class} 33010d565efSmrg@tab @code{#} 33110d565efSmrg@item @code{SEL} 33210d565efSmrg@tab @code{:} 33310d565efSmrg@item @code{char*} 33410d565efSmrg@tab @code{*} 33510d565efSmrg@item @code{enum} 33610d565efSmrg@tab an @code{enum} is encoded exactly as the integer type that the compiler uses for it, which depends on the enumeration 33710d565efSmrgvalues. Often the compiler users @code{unsigned int}, which is then encoded as @code{I}. 33810d565efSmrg@item unknown type 33910d565efSmrg@tab @code{?} 34010d565efSmrg@item Complex types 34110d565efSmrg@tab @code{j} followed by the inner type. For example @code{_Complex double} is encoded as "jd". 34210d565efSmrg@item bit-fields 34310d565efSmrg@tab @code{b} followed by the starting position of the bit-field, the type of the bit-field and the size of the bit-field (the bit-fields encoding was changed from the NeXT's compiler encoding, see below) 34410d565efSmrg@end multitable 34510d565efSmrg 34610d565efSmrg@c @sp 1 34710d565efSmrg 34810d565efSmrgThe encoding of bit-fields has changed to allow bit-fields to be 34910d565efSmrgproperly handled by the runtime functions that compute sizes and 35010d565efSmrgalignments of types that contain bit-fields. The previous encoding 35110d565efSmrgcontained only the size of the bit-field. Using only this information 35210d565efSmrgit is not possible to reliably compute the size occupied by the 35310d565efSmrgbit-field. This is very important in the presence of the Boehm's 35410d565efSmrggarbage collector because the objects are allocated using the typed 35510d565efSmrgmemory facility available in this collector. The typed memory 35610d565efSmrgallocation requires information about where the pointers are located 35710d565efSmrginside the object. 35810d565efSmrg 35910d565efSmrgThe position in the bit-field is the position, counting in bits, of the 36010d565efSmrgbit closest to the beginning of the structure. 36110d565efSmrg 36210d565efSmrgThe non-atomic types are encoded as follows: 36310d565efSmrg 36410d565efSmrg@c @sp 1 36510d565efSmrg 36610d565efSmrg@multitable @columnfractions .2 .8 36710d565efSmrg@item pointers 36810d565efSmrg@tab @samp{^} followed by the pointed type. 36910d565efSmrg@item arrays 37010d565efSmrg@tab @samp{[} followed by the number of elements in the array followed by the type of the elements followed by @samp{]} 37110d565efSmrg@item structures 37210d565efSmrg@tab @samp{@{} followed by the name of the structure (or @samp{?} if the structure is unnamed), the @samp{=} sign, the type of the members and by @samp{@}} 37310d565efSmrg@item unions 37410d565efSmrg@tab @samp{(} followed by the name of the structure (or @samp{?} if the union is unnamed), the @samp{=} sign, the type of the members followed by @samp{)} 37510d565efSmrg@item vectors 37610d565efSmrg@tab @samp{![} followed by the vector_size (the number of bytes composing the vector) followed by a comma, followed by the alignment (in bytes) of the vector, followed by the type of the elements followed by @samp{]} 37710d565efSmrg@end multitable 37810d565efSmrg 37910d565efSmrgHere are some types and their encodings, as they are generated by the 38010d565efSmrgcompiler on an i386 machine: 38110d565efSmrg 38210d565efSmrg@sp 1 38310d565efSmrg 38410d565efSmrg@multitable @columnfractions .60 .40 38510d565efSmrg@item Objective-C type 38610d565efSmrg@tab Compiler encoding 38710d565efSmrg@item 38810d565efSmrg@smallexample 38910d565efSmrgint a[10]; 39010d565efSmrg@end smallexample 39110d565efSmrg@tab @code{[10i]} 39210d565efSmrg@item 39310d565efSmrg@smallexample 39410d565efSmrgstruct @{ 39510d565efSmrg int i; 39610d565efSmrg float f[3]; 39710d565efSmrg int a:3; 39810d565efSmrg int b:2; 39910d565efSmrg char c; 40010d565efSmrg@} 40110d565efSmrg@end smallexample 40210d565efSmrg@tab @code{@{?=i[3f]b128i3b131i2c@}} 40310d565efSmrg@item 40410d565efSmrg@smallexample 40510d565efSmrgint a __attribute__ ((vector_size (16))); 40610d565efSmrg@end smallexample 40710d565efSmrg@tab @code{![16,16i]} (alignment depends on the machine) 40810d565efSmrg@end multitable 40910d565efSmrg 41010d565efSmrg@sp 1 41110d565efSmrg 41210d565efSmrgIn addition to the types the compiler also encodes the type 41310d565efSmrgspecifiers. The table below describes the encoding of the current 41410d565efSmrgObjective-C type specifiers: 41510d565efSmrg 41610d565efSmrg@sp 1 41710d565efSmrg 41810d565efSmrg@multitable @columnfractions .25 .75 41910d565efSmrg@item Specifier 42010d565efSmrg@tab Encoding 42110d565efSmrg@item @code{const} 42210d565efSmrg@tab @code{r} 42310d565efSmrg@item @code{in} 42410d565efSmrg@tab @code{n} 42510d565efSmrg@item @code{inout} 42610d565efSmrg@tab @code{N} 42710d565efSmrg@item @code{out} 42810d565efSmrg@tab @code{o} 42910d565efSmrg@item @code{bycopy} 43010d565efSmrg@tab @code{O} 43110d565efSmrg@item @code{byref} 43210d565efSmrg@tab @code{R} 43310d565efSmrg@item @code{oneway} 43410d565efSmrg@tab @code{V} 43510d565efSmrg@end multitable 43610d565efSmrg 43710d565efSmrg@sp 1 43810d565efSmrg 43910d565efSmrgThe type specifiers are encoded just before the type. Unlike types 44010d565efSmrghowever, the type specifiers are only encoded when they appear in method 44110d565efSmrgargument types. 44210d565efSmrg 44310d565efSmrgNote how @code{const} interacts with pointers: 44410d565efSmrg 44510d565efSmrg@sp 1 44610d565efSmrg 44710d565efSmrg@multitable @columnfractions .25 .75 44810d565efSmrg@item Objective-C type 44910d565efSmrg@tab Compiler encoding 45010d565efSmrg@item 45110d565efSmrg@smallexample 45210d565efSmrgconst int 45310d565efSmrg@end smallexample 45410d565efSmrg@tab @code{ri} 45510d565efSmrg@item 45610d565efSmrg@smallexample 45710d565efSmrgconst int* 45810d565efSmrg@end smallexample 45910d565efSmrg@tab @code{^ri} 46010d565efSmrg@item 46110d565efSmrg@smallexample 46210d565efSmrgint *const 46310d565efSmrg@end smallexample 46410d565efSmrg@tab @code{r^i} 46510d565efSmrg@end multitable 46610d565efSmrg 46710d565efSmrg@sp 1 46810d565efSmrg 46910d565efSmrg@code{const int*} is a pointer to a @code{const int}, and so is 47010d565efSmrgencoded as @code{^ri}. @code{int* const}, instead, is a @code{const} 47110d565efSmrgpointer to an @code{int}, and so is encoded as @code{r^i}. 47210d565efSmrg 47310d565efSmrgFinally, there is a complication when encoding @code{const char *} 47410d565efSmrgversus @code{char * const}. Because @code{char *} is encoded as 47510d565efSmrg@code{*} and not as @code{^c}, there is no way to express the fact 47610d565efSmrgthat @code{r} applies to the pointer or to the pointee. 47710d565efSmrg 47810d565efSmrgHence, it is assumed as a convention that @code{r*} means @code{const 47910d565efSmrgchar *} (since it is what is most often meant), and there is no way to 48010d565efSmrgencode @code{char *const}. @code{char *const} would simply be encoded 48110d565efSmrgas @code{*}, and the @code{const} is lost. 48210d565efSmrg 48310d565efSmrg@menu 48410d565efSmrg* Legacy type encoding:: 48510d565efSmrg* @@encode:: 48610d565efSmrg* Method signatures:: 48710d565efSmrg@end menu 48810d565efSmrg 48910d565efSmrg@node Legacy type encoding 49010d565efSmrg@subsection Legacy Type Encoding 49110d565efSmrg 49210d565efSmrgUnfortunately, historically GCC used to have a number of bugs in its 49310d565efSmrgencoding code. The NeXT runtime expects GCC to emit type encodings in 49410d565efSmrgthis historical format (compatible with GCC-3.3), so when using the 49510d565efSmrgNeXT runtime, GCC will introduce on purpose a number of incorrect 49610d565efSmrgencodings: 49710d565efSmrg 49810d565efSmrg@itemize @bullet 49910d565efSmrg 50010d565efSmrg@item 50110d565efSmrgthe read-only qualifier of the pointee gets emitted before the '^'. 50210d565efSmrgThe read-only qualifier of the pointer itself gets ignored, unless it 50310d565efSmrgis a typedef. Also, the 'r' is only emitted for the outermost type. 50410d565efSmrg 50510d565efSmrg@item 50610d565efSmrg32-bit longs are encoded as 'l' or 'L', but not always. For typedefs, 50710d565efSmrgthe compiler uses 'i' or 'I' instead if encoding a struct field or a 50810d565efSmrgpointer. 50910d565efSmrg 51010d565efSmrg@item 51110d565efSmrg@code{enum}s are always encoded as 'i' (int) even if they are actually 51210d565efSmrgunsigned or long. 51310d565efSmrg 51410d565efSmrg@end itemize 51510d565efSmrg 51610d565efSmrgIn addition to that, the NeXT runtime uses a different encoding for 51710d565efSmrgbitfields. It encodes them as @code{b} followed by the size, without 51810d565efSmrga bit offset or the underlying field type. 51910d565efSmrg 52010d565efSmrg@node @@encode 52110d565efSmrg@subsection @code{@@encode} 52210d565efSmrg 52310d565efSmrgGNU Objective-C supports the @code{@@encode} syntax that allows you to 52410d565efSmrgcreate a type encoding from a C/Objective-C type. For example, 52510d565efSmrg@code{@@encode(int)} is compiled by the compiler into @code{"i"}. 52610d565efSmrg 52710d565efSmrg@code{@@encode} does not support type qualifiers other than 52810d565efSmrg@code{const}. For example, @code{@@encode(const char*)} is valid and 52910d565efSmrgis compiled into @code{"r*"}, while @code{@@encode(bycopy char *)} is 53010d565efSmrginvalid and will cause a compilation error. 53110d565efSmrg 53210d565efSmrg@node Method signatures 53310d565efSmrg@subsection Method Signatures 53410d565efSmrg 53510d565efSmrgThis section documents the encoding of method types, which is rarely 53610d565efSmrgneeded to use Objective-C. You should skip it at a first reading; the 53710d565efSmrgruntime provides functions that will work on methods and can walk 53810d565efSmrgthrough the list of parameters and interpret them for you. These 53910d565efSmrgfunctions are part of the public ``API'' and are the preferred way to 54010d565efSmrginteract with method signatures from user code. 54110d565efSmrg 54210d565efSmrgBut if you need to debug a problem with method signatures and need to 54310d565efSmrgknow how they are implemented (i.e., the ``ABI''), read on. 54410d565efSmrg 54510d565efSmrgMethods have their ``signature'' encoded and made available to the 54610d565efSmrgruntime. The ``signature'' encodes all the information required to 54710d565efSmrgdynamically build invocations of the method at runtime: return type 54810d565efSmrgand arguments. 54910d565efSmrg 55010d565efSmrgThe ``signature'' is a null-terminated string, composed of the following: 55110d565efSmrg 55210d565efSmrg@itemize @bullet 55310d565efSmrg 55410d565efSmrg@item 55510d565efSmrgThe return type, including type qualifiers. For example, a method 55610d565efSmrgreturning @code{int} would have @code{i} here. 55710d565efSmrg 55810d565efSmrg@item 55910d565efSmrgThe total size (in bytes) required to pass all the parameters. This 56010d565efSmrgincludes the two hidden parameters (the object @code{self} and the 56110d565efSmrgmethod selector @code{_cmd}). 56210d565efSmrg 56310d565efSmrg@item 56410d565efSmrgEach argument, with the type encoding, followed by the offset (in 56510d565efSmrgbytes) of the argument in the list of parameters. 56610d565efSmrg 56710d565efSmrg@end itemize 56810d565efSmrg 56910d565efSmrgFor example, a method with no arguments and returning @code{int} would 57010d565efSmrghave the signature @code{i8@@0:4} if the size of a pointer is 4. The 57110d565efSmrgsignature is interpreted as follows: the @code{i} is the return type 57210d565efSmrg(an @code{int}), the @code{8} is the total size of the parameters in 57310d565efSmrgbytes (two pointers each of size 4), the @code{@@0} is the first 57410d565efSmrgparameter (an object at byte offset @code{0}) and @code{:4} is the 57510d565efSmrgsecond parameter (a @code{SEL} at byte offset @code{4}). 57610d565efSmrg 57710d565efSmrgYou can easily find more examples by running the ``strings'' program 57810d565efSmrgon an Objective-C object file compiled by GCC. You'll see a lot of 57910d565efSmrgstrings that look very much like @code{i8@@0:4}. They are signatures 58010d565efSmrgof Objective-C methods. 58110d565efSmrg 58210d565efSmrg 58310d565efSmrg@node Garbage Collection 58410d565efSmrg@section Garbage Collection 58510d565efSmrg 58610d565efSmrgThis section is specific for the GNU Objective-C runtime. If you are 58710d565efSmrgusing a different runtime, you can skip it. 58810d565efSmrg 58910d565efSmrgSupport for garbage collection with the GNU runtime has been added by 59010d565efSmrgusing a powerful conservative garbage collector, known as the 59110d565efSmrgBoehm-Demers-Weiser conservative garbage collector. 59210d565efSmrg 59310d565efSmrgTo enable the support for it you have to configure the compiler using 59410d565efSmrgan additional argument, @w{@option{--enable-objc-gc}}. This will 59510d565efSmrgbuild the boehm-gc library, and build an additional runtime library 59610d565efSmrgwhich has several enhancements to support the garbage collector. The 59710d565efSmrgnew library has a new name, @file{libobjc_gc.a} to not conflict with 59810d565efSmrgthe non-garbage-collected library. 59910d565efSmrg 60010d565efSmrgWhen the garbage collector is used, the objects are allocated using the 60110d565efSmrgso-called typed memory allocation mechanism available in the 60210d565efSmrgBoehm-Demers-Weiser collector. This mode requires precise information on 60310d565efSmrgwhere pointers are located inside objects. This information is computed 60410d565efSmrgonce per class, immediately after the class has been initialized. 60510d565efSmrg 60610d565efSmrgThere is a new runtime function @code{class_ivar_set_gcinvisible()} 60710d565efSmrgwhich can be used to declare a so-called @dfn{weak pointer} 60810d565efSmrgreference. Such a pointer is basically hidden for the garbage collector; 60910d565efSmrgthis can be useful in certain situations, especially when you want to 61010d565efSmrgkeep track of the allocated objects, yet allow them to be 61110d565efSmrgcollected. This kind of pointers can only be members of objects, you 61210d565efSmrgcannot declare a global pointer as a weak reference. Every type which is 61310d565efSmrga pointer type can be declared a weak pointer, including @code{id}, 61410d565efSmrg@code{Class} and @code{SEL}. 61510d565efSmrg 61610d565efSmrgHere is an example of how to use this feature. Suppose you want to 61710d565efSmrgimplement a class whose instances hold a weak pointer reference; the 61810d565efSmrgfollowing class does this: 61910d565efSmrg 62010d565efSmrg@smallexample 62110d565efSmrg 62210d565efSmrg@@interface WeakPointer : Object 62310d565efSmrg@{ 62410d565efSmrg const void* weakPointer; 62510d565efSmrg@} 62610d565efSmrg 62710d565efSmrg- initWithPointer:(const void*)p; 62810d565efSmrg- (const void*)weakPointer; 62910d565efSmrg@@end 63010d565efSmrg 63110d565efSmrg 63210d565efSmrg@@implementation WeakPointer 63310d565efSmrg 63410d565efSmrg+ (void)initialize 63510d565efSmrg@{ 63610d565efSmrg if (self == objc_lookUpClass ("WeakPointer")) 63710d565efSmrg class_ivar_set_gcinvisible (self, "weakPointer", YES); 63810d565efSmrg@} 63910d565efSmrg 64010d565efSmrg- initWithPointer:(const void*)p 64110d565efSmrg@{ 64210d565efSmrg weakPointer = p; 64310d565efSmrg return self; 64410d565efSmrg@} 64510d565efSmrg 64610d565efSmrg- (const void*)weakPointer 64710d565efSmrg@{ 64810d565efSmrg return weakPointer; 64910d565efSmrg@} 65010d565efSmrg 65110d565efSmrg@@end 65210d565efSmrg 65310d565efSmrg@end smallexample 65410d565efSmrg 65510d565efSmrgWeak pointers are supported through a new type character specifier 65610d565efSmrgrepresented by the @samp{!} character. The 65710d565efSmrg@code{class_ivar_set_gcinvisible()} function adds or removes this 65810d565efSmrgspecifier to the string type description of the instance variable named 65910d565efSmrgas argument. 66010d565efSmrg 66110d565efSmrg@c ========================================================================= 66210d565efSmrg@node Constant string objects 66310d565efSmrg@section Constant String Objects 66410d565efSmrg 66510d565efSmrgGNU Objective-C provides constant string objects that are generated 66610d565efSmrgdirectly by the compiler. You declare a constant string object by 66710d565efSmrgprefixing a C constant string with the character @samp{@@}: 66810d565efSmrg 66910d565efSmrg@smallexample 67010d565efSmrg id myString = @@"this is a constant string object"; 67110d565efSmrg@end smallexample 67210d565efSmrg 67310d565efSmrgThe constant string objects are by default instances of the 67410d565efSmrg@code{NXConstantString} class which is provided by the GNU Objective-C 67510d565efSmrgruntime. To get the definition of this class you must include the 67610d565efSmrg@file{objc/NXConstStr.h} header file. 67710d565efSmrg 67810d565efSmrgUser defined libraries may want to implement their own constant string 67910d565efSmrgclass. To be able to support them, the GNU Objective-C compiler provides 68010d565efSmrga new command line options @option{-fconstant-string-class=@var{class-name}}. 68110d565efSmrgThe provided class should adhere to a strict structure, the same 68210d565efSmrgas @code{NXConstantString}'s structure: 68310d565efSmrg 68410d565efSmrg@smallexample 68510d565efSmrg 68610d565efSmrg@@interface MyConstantStringClass 68710d565efSmrg@{ 68810d565efSmrg Class isa; 68910d565efSmrg char *c_string; 69010d565efSmrg unsigned int len; 69110d565efSmrg@} 69210d565efSmrg@@end 69310d565efSmrg 69410d565efSmrg@end smallexample 69510d565efSmrg 69610d565efSmrg@code{NXConstantString} inherits from @code{Object}; user class 69710d565efSmrglibraries may choose to inherit the customized constant string class 69810d565efSmrgfrom a different class than @code{Object}. There is no requirement in 69910d565efSmrgthe methods the constant string class has to implement, but the final 70010d565efSmrgivar layout of the class must be the compatible with the given 70110d565efSmrgstructure. 70210d565efSmrg 70310d565efSmrgWhen the compiler creates the statically allocated constant string 70410d565efSmrgobject, the @code{c_string} field will be filled by the compiler with 70510d565efSmrgthe string; the @code{length} field will be filled by the compiler with 70610d565efSmrgthe string length; the @code{isa} pointer will be filled with 70710d565efSmrg@code{NULL} by the compiler, and it will later be fixed up automatically 70810d565efSmrgat runtime by the GNU Objective-C runtime library to point to the class 70910d565efSmrgwhich was set by the @option{-fconstant-string-class} option when the 71010d565efSmrgobject file is loaded (if you wonder how it works behind the scenes, the 71110d565efSmrgname of the class to use, and the list of static objects to fixup, are 71210d565efSmrgstored by the compiler in the object file in a place where the GNU 71310d565efSmrgruntime library will find them at runtime). 71410d565efSmrg 71510d565efSmrgAs a result, when a file is compiled with the 71610d565efSmrg@option{-fconstant-string-class} option, all the constant string objects 71710d565efSmrgwill be instances of the class specified as argument to this option. It 71810d565efSmrgis possible to have multiple compilation units referring to different 71910d565efSmrgconstant string classes, neither the compiler nor the linker impose any 72010d565efSmrgrestrictions in doing this. 72110d565efSmrg 72210d565efSmrg@c ========================================================================= 72310d565efSmrg@node compatibility_alias 72410d565efSmrg@section @code{compatibility_alias} 72510d565efSmrg 72610d565efSmrgThe keyword @code{@@compatibility_alias} allows you to define a class name 72710d565efSmrgas equivalent to another class name. For example: 72810d565efSmrg 72910d565efSmrg@smallexample 73010d565efSmrg@@compatibility_alias WOApplication GSWApplication; 73110d565efSmrg@end smallexample 73210d565efSmrg 73310d565efSmrgtells the compiler that each time it encounters @code{WOApplication} as 73410d565efSmrga class name, it should replace it with @code{GSWApplication} (that is, 73510d565efSmrg@code{WOApplication} is just an alias for @code{GSWApplication}). 73610d565efSmrg 73710d565efSmrgThere are some constraints on how this can be used--- 73810d565efSmrg 73910d565efSmrg@itemize @bullet 74010d565efSmrg 74110d565efSmrg@item @code{WOApplication} (the alias) must not be an existing class; 74210d565efSmrg 74310d565efSmrg@item @code{GSWApplication} (the real class) must be an existing class. 74410d565efSmrg 74510d565efSmrg@end itemize 74610d565efSmrg 74710d565efSmrg@c ========================================================================= 74810d565efSmrg@node Exceptions 74910d565efSmrg@section Exceptions 75010d565efSmrg 75110d565efSmrgGNU Objective-C provides exception support built into the language, as 75210d565efSmrgin the following example: 75310d565efSmrg 75410d565efSmrg@smallexample 75510d565efSmrg @@try @{ 75610d565efSmrg @dots{} 75710d565efSmrg @@throw expr; 75810d565efSmrg @dots{} 75910d565efSmrg @} 76010d565efSmrg @@catch (AnObjCClass *exc) @{ 76110d565efSmrg @dots{} 76210d565efSmrg @@throw expr; 76310d565efSmrg @dots{} 76410d565efSmrg @@throw; 76510d565efSmrg @dots{} 76610d565efSmrg @} 76710d565efSmrg @@catch (AnotherClass *exc) @{ 76810d565efSmrg @dots{} 76910d565efSmrg @} 77010d565efSmrg @@catch (id allOthers) @{ 77110d565efSmrg @dots{} 77210d565efSmrg @} 77310d565efSmrg @@finally @{ 77410d565efSmrg @dots{} 77510d565efSmrg @@throw expr; 77610d565efSmrg @dots{} 77710d565efSmrg @} 77810d565efSmrg@end smallexample 77910d565efSmrg 78010d565efSmrgThe @code{@@throw} statement may appear anywhere in an Objective-C or 78110d565efSmrgObjective-C++ program; when used inside of a @code{@@catch} block, the 78210d565efSmrg@code{@@throw} may appear without an argument (as shown above), in 78310d565efSmrgwhich case the object caught by the @code{@@catch} will be rethrown. 78410d565efSmrg 78510d565efSmrgNote that only (pointers to) Objective-C objects may be thrown and 78610d565efSmrgcaught using this scheme. When an object is thrown, it will be caught 78710d565efSmrgby the nearest @code{@@catch} clause capable of handling objects of 78810d565efSmrgthat type, analogously to how @code{catch} blocks work in C++ and 78910d565efSmrgJava. A @code{@@catch(id @dots{})} clause (as shown above) may also 79010d565efSmrgbe provided to catch any and all Objective-C exceptions not caught by 79110d565efSmrgprevious @code{@@catch} clauses (if any). 79210d565efSmrg 79310d565efSmrgThe @code{@@finally} clause, if present, will be executed upon exit 79410d565efSmrgfrom the immediately preceding @code{@@try @dots{} @@catch} section. 79510d565efSmrgThis will happen regardless of whether any exceptions are thrown, 79610d565efSmrgcaught or rethrown inside the @code{@@try @dots{} @@catch} section, 79710d565efSmrganalogously to the behavior of the @code{finally} clause in Java. 79810d565efSmrg 79910d565efSmrgThere are several caveats to using the new exception mechanism: 80010d565efSmrg 80110d565efSmrg@itemize @bullet 80210d565efSmrg@item 80310d565efSmrgThe @option{-fobjc-exceptions} command line option must be used when 80410d565efSmrgcompiling Objective-C files that use exceptions. 80510d565efSmrg 80610d565efSmrg@item 80710d565efSmrgWith the GNU runtime, exceptions are always implemented as ``native'' 80810d565efSmrgexceptions and it is recommended that the @option{-fexceptions} and 80910d565efSmrg@option{-shared-libgcc} options are used when linking. 81010d565efSmrg 81110d565efSmrg@item 81210d565efSmrgWith the NeXT runtime, although currently designed to be binary 81310d565efSmrgcompatible with @code{NS_HANDLER}-style idioms provided by the 81410d565efSmrg@code{NSException} class, the new exceptions can only be used on Mac 81510d565efSmrgOS X 10.3 (Panther) and later systems, due to additional functionality 81610d565efSmrgneeded in the NeXT Objective-C runtime. 81710d565efSmrg 81810d565efSmrg@item 81910d565efSmrgAs mentioned above, the new exceptions do not support handling 82010d565efSmrgtypes other than Objective-C objects. Furthermore, when used from 82110d565efSmrgObjective-C++, the Objective-C exception model does not interoperate with C++ 82210d565efSmrgexceptions at this time. This means you cannot @code{@@throw} an exception 82310d565efSmrgfrom Objective-C and @code{catch} it in C++, or vice versa 82410d565efSmrg(i.e., @code{throw @dots{} @@catch}). 82510d565efSmrg@end itemize 82610d565efSmrg 82710d565efSmrg@c ========================================================================= 82810d565efSmrg@node Synchronization 82910d565efSmrg@section Synchronization 83010d565efSmrg 83110d565efSmrgGNU Objective-C provides support for synchronized blocks: 83210d565efSmrg 83310d565efSmrg@smallexample 83410d565efSmrg @@synchronized (ObjCClass *guard) @{ 83510d565efSmrg @dots{} 83610d565efSmrg @} 83710d565efSmrg@end smallexample 83810d565efSmrg 83910d565efSmrgUpon entering the @code{@@synchronized} block, a thread of execution 84010d565efSmrgshall first check whether a lock has been placed on the corresponding 84110d565efSmrg@code{guard} object by another thread. If it has, the current thread 84210d565efSmrgshall wait until the other thread relinquishes its lock. Once 84310d565efSmrg@code{guard} becomes available, the current thread will place its own 84410d565efSmrglock on it, execute the code contained in the @code{@@synchronized} 84510d565efSmrgblock, and finally relinquish the lock (thereby making @code{guard} 84610d565efSmrgavailable to other threads). 84710d565efSmrg 84810d565efSmrgUnlike Java, Objective-C does not allow for entire methods to be 84910d565efSmrgmarked @code{@@synchronized}. Note that throwing exceptions out of 85010d565efSmrg@code{@@synchronized} blocks is allowed, and will cause the guarding 85110d565efSmrgobject to be unlocked properly. 85210d565efSmrg 85310d565efSmrgBecause of the interactions between synchronization and exception 85410d565efSmrghandling, you can only use @code{@@synchronized} when compiling with 85510d565efSmrgexceptions enabled, that is with the command line option 85610d565efSmrg@option{-fobjc-exceptions}. 85710d565efSmrg 85810d565efSmrg 85910d565efSmrg@c ========================================================================= 86010d565efSmrg@node Fast enumeration 86110d565efSmrg@section Fast Enumeration 86210d565efSmrg 86310d565efSmrg@menu 86410d565efSmrg* Using fast enumeration:: 86510d565efSmrg* c99-like fast enumeration syntax:: 86610d565efSmrg* Fast enumeration details:: 86710d565efSmrg* Fast enumeration protocol:: 86810d565efSmrg@end menu 86910d565efSmrg 87010d565efSmrg@c ================================ 87110d565efSmrg@node Using fast enumeration 87210d565efSmrg@subsection Using Fast Enumeration 87310d565efSmrg 87410d565efSmrgGNU Objective-C provides support for the fast enumeration syntax: 87510d565efSmrg 87610d565efSmrg@smallexample 87710d565efSmrg id array = @dots{}; 87810d565efSmrg id object; 87910d565efSmrg 88010d565efSmrg for (object in array) 88110d565efSmrg @{ 88210d565efSmrg /* Do something with 'object' */ 88310d565efSmrg @} 88410d565efSmrg@end smallexample 88510d565efSmrg 88610d565efSmrg@code{array} needs to be an Objective-C object (usually a collection 88710d565efSmrgobject, for example an array, a dictionary or a set) which implements 88810d565efSmrgthe ``Fast Enumeration Protocol'' (see below). If you are using a 88910d565efSmrgFoundation library such as GNUstep Base or Apple Cocoa Foundation, all 89010d565efSmrgcollection objects in the library implement this protocol and can be 89110d565efSmrgused in this way. 89210d565efSmrg 89310d565efSmrgThe code above would iterate over all objects in @code{array}. For 89410d565efSmrgeach of them, it assigns it to @code{object}, then executes the 89510d565efSmrg@code{Do something with 'object'} statements. 89610d565efSmrg 89710d565efSmrgHere is a fully worked-out example using a Foundation library (which 89810d565efSmrgprovides the implementation of @code{NSArray}, @code{NSString} and 89910d565efSmrg@code{NSLog}): 90010d565efSmrg 90110d565efSmrg@smallexample 90210d565efSmrg NSArray *array = [NSArray arrayWithObjects: @@"1", @@"2", @@"3", nil]; 90310d565efSmrg NSString *object; 90410d565efSmrg 90510d565efSmrg for (object in array) 90610d565efSmrg NSLog (@@"Iterating over %@@", object); 90710d565efSmrg@end smallexample 90810d565efSmrg 90910d565efSmrg 91010d565efSmrg@c ================================ 91110d565efSmrg@node c99-like fast enumeration syntax 91210d565efSmrg@subsection C99-Like Fast Enumeration Syntax 91310d565efSmrg 91410d565efSmrgA c99-like declaration syntax is also allowed: 91510d565efSmrg 91610d565efSmrg@smallexample 91710d565efSmrg id array = @dots{}; 91810d565efSmrg 91910d565efSmrg for (id object in array) 92010d565efSmrg @{ 92110d565efSmrg /* Do something with 'object' */ 92210d565efSmrg @} 92310d565efSmrg@end smallexample 92410d565efSmrg 92510d565efSmrgthis is completely equivalent to: 92610d565efSmrg 92710d565efSmrg@smallexample 92810d565efSmrg id array = @dots{}; 92910d565efSmrg 93010d565efSmrg @{ 93110d565efSmrg id object; 93210d565efSmrg for (object in array) 93310d565efSmrg @{ 93410d565efSmrg /* Do something with 'object' */ 93510d565efSmrg @} 93610d565efSmrg @} 93710d565efSmrg@end smallexample 93810d565efSmrg 93910d565efSmrgbut can save some typing. 94010d565efSmrg 94110d565efSmrgNote that the option @option{-std=c99} is not required to allow this 94210d565efSmrgsyntax in Objective-C. 94310d565efSmrg 94410d565efSmrg@c ================================ 94510d565efSmrg@node Fast enumeration details 94610d565efSmrg@subsection Fast Enumeration Details 94710d565efSmrg 94810d565efSmrgHere is a more technical description with the gory details. Consider the code 94910d565efSmrg 95010d565efSmrg@smallexample 95110d565efSmrg for (@var{object expression} in @var{collection expression}) 95210d565efSmrg @{ 95310d565efSmrg @var{statements} 95410d565efSmrg @} 95510d565efSmrg@end smallexample 95610d565efSmrg 95710d565efSmrghere is what happens when you run it: 95810d565efSmrg 95910d565efSmrg@itemize @bullet 96010d565efSmrg@item 96110d565efSmrg@code{@var{collection expression}} is evaluated exactly once and the 96210d565efSmrgresult is used as the collection object to iterate over. This means 96310d565efSmrgit is safe to write code such as @code{for (object in [NSDictionary 96410d565efSmrgkeyEnumerator]) @dots{}}. 96510d565efSmrg 96610d565efSmrg@item 96710d565efSmrgthe iteration is implemented by the compiler by repeatedly getting 96810d565efSmrgbatches of objects from the collection object using the fast 96910d565efSmrgenumeration protocol (see below), then iterating over all objects in 97010d565efSmrgthe batch. This is faster than a normal enumeration where objects are 97110d565efSmrgretrieved one by one (hence the name ``fast enumeration''). 97210d565efSmrg 97310d565efSmrg@item 97410d565efSmrgif there are no objects in the collection, then 97510d565efSmrg@code{@var{object expression}} is set to @code{nil} and the loop 97610d565efSmrgimmediately terminates. 97710d565efSmrg 97810d565efSmrg@item 97910d565efSmrgif there are objects in the collection, then for each object in the 98010d565efSmrgcollection (in the order they are returned) @code{@var{object expression}} 98110d565efSmrgis set to the object, then @code{@var{statements}} are executed. 98210d565efSmrg 98310d565efSmrg@item 98410d565efSmrg@code{@var{statements}} can contain @code{break} and @code{continue} 98510d565efSmrgcommands, which will abort the iteration or skip to the next loop 98610d565efSmrgiteration as expected. 98710d565efSmrg 98810d565efSmrg@item 98910d565efSmrgwhen the iteration ends because there are no more objects to iterate 99010d565efSmrgover, @code{@var{object expression}} is set to @code{nil}. This allows 99110d565efSmrgyou to determine whether the iteration finished because a @code{break} 99210d565efSmrgcommand was used (in which case @code{@var{object expression}} will remain 99310d565efSmrgset to the last object that was iterated over) or because it iterated 99410d565efSmrgover all the objects (in which case @code{@var{object expression}} will be 99510d565efSmrgset to @code{nil}). 99610d565efSmrg 99710d565efSmrg@item 99810d565efSmrg@code{@var{statements}} must not make any changes to the collection 99910d565efSmrgobject; if they do, it is a hard error and the fast enumeration 100010d565efSmrgterminates by invoking @code{objc_enumerationMutation}, a runtime 100110d565efSmrgfunction that normally aborts the program but which can be customized 100210d565efSmrgby Foundation libraries via @code{objc_set_mutation_handler} to do 100310d565efSmrgsomething different, such as raising an exception. 100410d565efSmrg 100510d565efSmrg@end itemize 100610d565efSmrg 100710d565efSmrg@c ================================ 100810d565efSmrg@node Fast enumeration protocol 100910d565efSmrg@subsection Fast Enumeration Protocol 101010d565efSmrg 101110d565efSmrgIf you want your own collection object to be usable with fast 101210d565efSmrgenumeration, you need to have it implement the method 101310d565efSmrg 101410d565efSmrg@smallexample 101510d565efSmrg- (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state 101610d565efSmrg objects: (id *)objects 101710d565efSmrg count: (unsigned long)len; 101810d565efSmrg@end smallexample 101910d565efSmrg 102010d565efSmrgwhere @code{NSFastEnumerationState} must be defined in your code as follows: 102110d565efSmrg 102210d565efSmrg@smallexample 102310d565efSmrgtypedef struct 102410d565efSmrg@{ 102510d565efSmrg unsigned long state; 102610d565efSmrg id *itemsPtr; 102710d565efSmrg unsigned long *mutationsPtr; 102810d565efSmrg unsigned long extra[5]; 102910d565efSmrg@} NSFastEnumerationState; 103010d565efSmrg@end smallexample 103110d565efSmrg 103210d565efSmrgIf no @code{NSFastEnumerationState} is defined in your code, the 103310d565efSmrgcompiler will automatically replace @code{NSFastEnumerationState *} 103410d565efSmrgwith @code{struct __objcFastEnumerationState *}, where that type is 103510d565efSmrgsilently defined by the compiler in an identical way. This can be 103610d565efSmrgconfusing and we recommend that you define 103710d565efSmrg@code{NSFastEnumerationState} (as shown above) instead. 103810d565efSmrg 103910d565efSmrgThe method is called repeatedly during a fast enumeration to retrieve 104010d565efSmrgbatches of objects. Each invocation of the method should retrieve the 104110d565efSmrgnext batch of objects. 104210d565efSmrg 104310d565efSmrgThe return value of the method is the number of objects in the current 104410d565efSmrgbatch; this should not exceed @code{len}, which is the maximum size of 104510d565efSmrga batch as requested by the caller. The batch itself is returned in 104610d565efSmrgthe @code{itemsPtr} field of the @code{NSFastEnumerationState} struct. 104710d565efSmrg 104810d565efSmrgTo help with returning the objects, the @code{objects} array is a C 104910d565efSmrgarray preallocated by the caller (on the stack) of size @code{len}. 105010d565efSmrgIn many cases you can put the objects you want to return in that 105110d565efSmrg@code{objects} array, then do @code{itemsPtr = objects}. But you 105210d565efSmrgdon't have to; if your collection already has the objects to return in 105310d565efSmrgsome form of C array, it could return them from there instead. 105410d565efSmrg 105510d565efSmrgThe @code{state} and @code{extra} fields of the 105610d565efSmrg@code{NSFastEnumerationState} structure allows your collection object 105710d565efSmrgto keep track of the state of the enumeration. In a simple array 105810d565efSmrgimplementation, @code{state} may keep track of the index of the last 105910d565efSmrgobject that was returned, and @code{extra} may be unused. 106010d565efSmrg 106110d565efSmrgThe @code{mutationsPtr} field of the @code{NSFastEnumerationState} is 106210d565efSmrgused to keep track of mutations. It should point to a number; before 106310d565efSmrgworking on each object, the fast enumeration loop will check that this 106410d565efSmrgnumber has not changed. If it has, a mutation has happened and the 106510d565efSmrgfast enumeration will abort. So, @code{mutationsPtr} could be set to 106610d565efSmrgpoint to some sort of version number of your collection, which is 106710d565efSmrgincreased by one every time there is a change (for example when an 106810d565efSmrgobject is added or removed). Or, if you are content with less strict 106910d565efSmrgmutation checks, it could point to the number of objects in your 107010d565efSmrgcollection or some other value that can be checked to perform an 107110d565efSmrgapproximate check that the collection has not been mutated. 107210d565efSmrg 107310d565efSmrgFinally, note how we declared the @code{len} argument and the return 107410d565efSmrgvalue to be of type @code{unsigned long}. They could also be declared 107510d565efSmrgto be of type @code{unsigned int} and everything would still work. 107610d565efSmrg 107710d565efSmrg@c ========================================================================= 107810d565efSmrg@node Messaging with the GNU Objective-C runtime 107910d565efSmrg@section Messaging with the GNU Objective-C Runtime 108010d565efSmrg 108110d565efSmrgThis section is specific for the GNU Objective-C runtime. If you are 108210d565efSmrgusing a different runtime, you can skip it. 108310d565efSmrg 108410d565efSmrgThe implementation of messaging in the GNU Objective-C runtime is 108510d565efSmrgdesigned to be portable, and so is based on standard C. 108610d565efSmrg 108710d565efSmrgSending a message in the GNU Objective-C runtime is composed of two 108810d565efSmrgseparate steps. First, there is a call to the lookup function, 108910d565efSmrg@code{objc_msg_lookup ()} (or, in the case of messages to super, 109010d565efSmrg@code{objc_msg_lookup_super ()}). This runtime function takes as 109110d565efSmrgargument the receiver and the selector of the method to be called; it 109210d565efSmrgreturns the @code{IMP}, that is a pointer to the function implementing 109310d565efSmrgthe method. The second step of method invocation consists of casting 109410d565efSmrgthis pointer function to the appropriate function pointer type, and 109510d565efSmrgcalling the function pointed to it with the right arguments. 109610d565efSmrg 109710d565efSmrgFor example, when the compiler encounters a method invocation such as 109810d565efSmrg@code{[object init]}, it compiles it into a call to 109910d565efSmrg@code{objc_msg_lookup (object, @@selector(init))} followed by a cast 110010d565efSmrgof the returned value to the appropriate function pointer type, and 110110d565efSmrgthen it calls it. 110210d565efSmrg 110310d565efSmrg@menu 110410d565efSmrg* Dynamically registering methods:: 110510d565efSmrg* Forwarding hook:: 110610d565efSmrg@end menu 110710d565efSmrg 110810d565efSmrg@c ========================================================================= 110910d565efSmrg@node Dynamically registering methods 111010d565efSmrg@subsection Dynamically Registering Methods 111110d565efSmrg 111210d565efSmrgIf @code{objc_msg_lookup()} does not find a suitable method 111310d565efSmrgimplementation, because the receiver does not implement the required 111410d565efSmrgmethod, it tries to see if the class can dynamically register the 111510d565efSmrgmethod. 111610d565efSmrg 111710d565efSmrgTo do so, the runtime checks if the class of the receiver implements 111810d565efSmrgthe method 111910d565efSmrg 112010d565efSmrg@smallexample 112110d565efSmrg+ (BOOL) resolveInstanceMethod: (SEL)selector; 112210d565efSmrg@end smallexample 112310d565efSmrg 112410d565efSmrgin the case of an instance method, or 112510d565efSmrg 112610d565efSmrg@smallexample 112710d565efSmrg+ (BOOL) resolveClassMethod: (SEL)selector; 112810d565efSmrg@end smallexample 112910d565efSmrg 113010d565efSmrgin the case of a class method. If the class implements it, the 113110d565efSmrgruntime invokes it, passing as argument the selector of the original 113210d565efSmrgmethod, and if it returns @code{YES}, the runtime tries the lookup 113310d565efSmrgagain, which could now succeed if a matching method was added 113410d565efSmrgdynamically by @code{+resolveInstanceMethod:} or 113510d565efSmrg@code{+resolveClassMethod:}. 113610d565efSmrg 113710d565efSmrgThis allows classes to dynamically register methods (by adding them to 113810d565efSmrgthe class using @code{class_addMethod}) when they are first called. 113910d565efSmrgTo do so, a class should implement @code{+resolveInstanceMethod:} (or, 114010d565efSmrgdepending on the case, @code{+resolveClassMethod:}) and have it 114110d565efSmrgrecognize the selectors of methods that can be registered dynamically 114210d565efSmrgat runtime, register them, and return @code{YES}. It should return 114310d565efSmrg@code{NO} for methods that it does not dynamically registered at 114410d565efSmrgruntime. 114510d565efSmrg 114610d565efSmrgIf @code{+resolveInstanceMethod:} (or @code{+resolveClassMethod:}) is 114710d565efSmrgnot implemented or returns @code{NO}, the runtime then tries the 114810d565efSmrgforwarding hook. 114910d565efSmrg 115010d565efSmrgSupport for @code{+resolveInstanceMethod:} and 115110d565efSmrg@code{resolveClassMethod:} was added to the GNU Objective-C runtime in 115210d565efSmrgGCC version 4.6. 115310d565efSmrg 115410d565efSmrg@c ========================================================================= 115510d565efSmrg@node Forwarding hook 115610d565efSmrg@subsection Forwarding Hook 115710d565efSmrg 115810d565efSmrgThe GNU Objective-C runtime provides a hook, called 115910d565efSmrg@code{__objc_msg_forward2}, which is called by 116010d565efSmrg@code{objc_msg_lookup()} when it cannot find a method implementation in 116110d565efSmrgthe runtime tables and after calling @code{+resolveInstanceMethod:} 116210d565efSmrgand @code{+resolveClassMethod:} has been attempted and did not succeed 116310d565efSmrgin dynamically registering the method. 116410d565efSmrg 116510d565efSmrgTo configure the hook, you set the global variable 116610d565efSmrg@code{__objc_msg_forward2} to a function with the same argument and 116710d565efSmrgreturn types of @code{objc_msg_lookup()}. When 116810d565efSmrg@code{objc_msg_lookup()} cannot find a method implementation, it 116910d565efSmrginvokes the hook function you provided to get a method implementation 117010d565efSmrgto return. So, in practice @code{__objc_msg_forward2} allows you to 117110d565efSmrgextend @code{objc_msg_lookup()} by adding some custom code that is 117210d565efSmrgcalled to do a further lookup when no standard method implementation 117310d565efSmrgcan be found using the normal lookup. 117410d565efSmrg 117510d565efSmrgThis hook is generally reserved for ``Foundation'' libraries such as 117610d565efSmrgGNUstep Base, which use it to implement their high-level method 117710d565efSmrgforwarding API, typically based around the @code{forwardInvocation:} 117810d565efSmrgmethod. So, unless you are implementing your own ``Foundation'' 117910d565efSmrglibrary, you should not set this hook. 118010d565efSmrg 118110d565efSmrgIn a typical forwarding implementation, the @code{__objc_msg_forward2} 118210d565efSmrghook function determines the argument and return type of the method 118310d565efSmrgthat is being looked up, and then creates a function that takes these 118410d565efSmrgarguments and has that return type, and returns it to the caller. 118510d565efSmrgCreating this function is non-trivial and is typically performed using 118610d565efSmrga dedicated library such as @code{libffi}. 118710d565efSmrg 118810d565efSmrgThe forwarding method implementation thus created is returned by 118910d565efSmrg@code{objc_msg_lookup()} and is executed as if it was a normal method 119010d565efSmrgimplementation. When the forwarding method implementation is called, 119110d565efSmrgit is usually expected to pack all arguments into some sort of object 119210d565efSmrg(typically, an @code{NSInvocation} in a ``Foundation'' library), and 119310d565efSmrghand it over to the programmer (@code{forwardInvocation:}) who is then 119410d565efSmrgallowed to manipulate the method invocation using a high-level API 119510d565efSmrgprovided by the ``Foundation'' library. For example, the programmer 119610d565efSmrgmay want to examine the method invocation arguments and name and 119710d565efSmrgpotentially change them before forwarding the method invocation to one 119810d565efSmrgor more local objects (@code{performInvocation:}) or even to remote 119910d565efSmrgobjects (by using Distributed Objects or some other mechanism). When 120010d565efSmrgall this completes, the return value is passed back and must be 120110d565efSmrgreturned correctly to the original caller. 120210d565efSmrg 120310d565efSmrgNote that the GNU Objective-C runtime currently provides no support 120410d565efSmrgfor method forwarding or method invocations other than the 120510d565efSmrg@code{__objc_msg_forward2} hook. 120610d565efSmrg 120710d565efSmrgIf the forwarding hook does not exist or returns @code{NULL}, the 120810d565efSmrgruntime currently attempts forwarding using an older, deprecated API, 120910d565efSmrgand if that fails, it aborts the program. In future versions of the 121010d565efSmrgGNU Objective-C runtime, the runtime will immediately abort. 1211