1@c Copyright (C) 1988-2020 Free Software Foundation, Inc. 2@c This is part of the GCC manual. 3@c For copying conditions, see the file gcc.texi. 4 5@node Objective-C 6@comment node-name, next, previous, up 7 8@chapter GNU Objective-C Features 9 10This document is meant to describe some of the GNU Objective-C 11features. It is not intended to teach you Objective-C. There are 12several resources on the Internet that present the language. 13 14@menu 15* GNU Objective-C runtime API:: 16* Executing code before main:: 17* Type encoding:: 18* Garbage Collection:: 19* Constant string objects:: 20* compatibility_alias:: 21* Exceptions:: 22* Synchronization:: 23* Fast enumeration:: 24* Messaging with the GNU Objective-C runtime:: 25@end menu 26 27@c ========================================================================= 28@node GNU Objective-C runtime API 29@section GNU Objective-C Runtime API 30 31This section is specific for the GNU Objective-C runtime. If you are 32using a different runtime, you can skip it. 33 34The GNU Objective-C runtime provides an API that allows you to 35interact with the Objective-C runtime system, querying the live 36runtime structures and even manipulating them. This allows you for 37example to inspect and navigate classes, methods and protocols; to 38define new classes or new methods, and even to modify existing classes 39or protocols. 40 41If you are using a ``Foundation'' library such as GNUstep-Base, this 42library will provide you with a rich set of functionality to do most 43of the inspection tasks, and you probably will only need direct access 44to the GNU Objective-C runtime API to define new classes or methods. 45 46@menu 47* Modern GNU Objective-C runtime API:: 48* Traditional GNU Objective-C runtime API:: 49@end menu 50 51@c ========================================================================= 52@node Modern GNU Objective-C runtime API 53@subsection Modern GNU Objective-C Runtime API 54 55The GNU Objective-C runtime provides an API which is similar to the 56one provided by the ``Objective-C 2.0'' Apple/NeXT Objective-C 57runtime. The API is documented in the public header files of the GNU 58Objective-C runtime: 59 60@itemize @bullet 61 62@item 63@file{objc/objc.h}: this is the basic Objective-C header file, 64defining the basic Objective-C types such as @code{id}, @code{Class} 65and @code{BOOL}. You have to include this header to do almost 66anything with Objective-C. 67 68@item 69@file{objc/runtime.h}: this header declares most of the public runtime 70API functions allowing you to inspect and manipulate the Objective-C 71runtime data structures. These functions are fairly standardized 72across Objective-C runtimes and are almost identical to the Apple/NeXT 73Objective-C runtime ones. It does not declare functions in some 74specialized areas (constructing and forwarding message invocations, 75threading) which are in the other headers below. You have to include 76@file{objc/objc.h} and @file{objc/runtime.h} to use any of the 77functions, such as @code{class_getName()}, declared in 78@file{objc/runtime.h}. 79 80@item 81@file{objc/message.h}: this header declares public functions used to 82construct, deconstruct and forward message invocations. Because 83messaging is done in quite a different way on different runtimes, 84functions in this header are specific to the GNU Objective-C runtime 85implementation. 86 87@item 88@file{objc/objc-exception.h}: this header declares some public 89functions related to Objective-C exceptions. For example functions in 90this header allow you to throw an Objective-C exception from plain 91C/C++ code. 92 93@item 94@file{objc/objc-sync.h}: this header declares some public functions 95related to the Objective-C @code{@@synchronized()} syntax, allowing 96you to emulate an Objective-C @code{@@synchronized()} block in plain 97C/C++ code. 98 99@item 100@file{objc/thr.h}: this header declares a public runtime API threading 101layer that is only provided by the GNU Objective-C runtime. It 102declares functions such as @code{objc_mutex_lock()}, which provide a 103platform-independent set of threading functions. 104 105@end itemize 106 107The header files contain detailed documentation for each function in 108the GNU Objective-C runtime API. 109 110@c ========================================================================= 111@node Traditional GNU Objective-C runtime API 112@subsection Traditional GNU Objective-C Runtime API 113 114The GNU Objective-C runtime used to provide a different API, which we 115call the ``traditional'' GNU Objective-C runtime API. Functions 116belonging to this API are easy to recognize because they use a 117different naming convention, such as @code{class_get_super_class()} 118(traditional API) instead of @code{class_getSuperclass()} (modern 119API). Software using this API includes the file 120@file{objc/objc-api.h} where it is declared. 121 122Starting with GCC 4.7.0, the traditional GNU runtime API is no longer 123available. 124 125@c ========================================================================= 126@node Executing code before main 127@section @code{+load}: Executing Code before @code{main} 128 129This section is specific for the GNU Objective-C runtime. If you are 130using a different runtime, you can skip it. 131 132The GNU Objective-C runtime provides a way that allows you to execute 133code before the execution of the program enters the @code{main} 134function. The code is executed on a per-class and a per-category basis, 135through a special class method @code{+load}. 136 137This facility is very useful if you want to initialize global variables 138which can be accessed by the program directly, without sending a message 139to the class first. The usual way to initialize global variables, in the 140@code{+initialize} method, might not be useful because 141@code{+initialize} is only called when the first message is sent to a 142class object, which in some cases could be too late. 143 144Suppose for example you have a @code{FileStream} class that declares 145@code{Stdin}, @code{Stdout} and @code{Stderr} as global variables, like 146below: 147 148@smallexample 149 150FileStream *Stdin = nil; 151FileStream *Stdout = nil; 152FileStream *Stderr = nil; 153 154@@implementation FileStream 155 156+ (void)initialize 157@{ 158 Stdin = [[FileStream new] initWithFd:0]; 159 Stdout = [[FileStream new] initWithFd:1]; 160 Stderr = [[FileStream new] initWithFd:2]; 161@} 162 163/* @r{Other methods here} */ 164@@end 165 166@end smallexample 167 168In this example, the initialization of @code{Stdin}, @code{Stdout} and 169@code{Stderr} in @code{+initialize} occurs too late. The programmer can 170send a message to one of these objects before the variables are actually 171initialized, thus sending messages to the @code{nil} object. The 172@code{+initialize} method which actually initializes the global 173variables is not invoked until the first message is sent to the class 174object. The solution would require these variables to be initialized 175just before entering @code{main}. 176 177The correct solution of the above problem is to use the @code{+load} 178method instead of @code{+initialize}: 179 180@smallexample 181 182@@implementation FileStream 183 184+ (void)load 185@{ 186 Stdin = [[FileStream new] initWithFd:0]; 187 Stdout = [[FileStream new] initWithFd:1]; 188 Stderr = [[FileStream new] initWithFd:2]; 189@} 190 191/* @r{Other methods here} */ 192@@end 193 194@end smallexample 195 196The @code{+load} is a method that is not overridden by categories. If a 197class and a category of it both implement @code{+load}, both methods are 198invoked. This allows some additional initializations to be performed in 199a category. 200 201This mechanism is not intended to be a replacement for @code{+initialize}. 202You should be aware of its limitations when you decide to use it 203instead of @code{+initialize}. 204 205@menu 206* What you can and what you cannot do in +load:: 207@end menu 208 209 210@node What you can and what you cannot do in +load 211@subsection What You Can and Cannot Do in @code{+load} 212 213@code{+load} is to be used only as a last resort. Because it is 214executed very early, most of the Objective-C runtime machinery will 215not be ready when @code{+load} is executed; hence @code{+load} works 216best for executing C code that is independent on the Objective-C 217runtime. 218 219The @code{+load} implementation in the GNU runtime guarantees you the 220following things: 221 222@itemize @bullet 223 224@item 225you can write whatever C code you like; 226 227@item 228you can allocate and send messages to objects whose class is implemented 229in the same file; 230 231@item 232the @code{+load} implementation of all super classes of a class are 233executed before the @code{+load} of that class is executed; 234 235@item 236the @code{+load} implementation of a class is executed before the 237@code{+load} implementation of any category. 238 239@end itemize 240 241In particular, the following things, even if they can work in a 242particular case, are not guaranteed: 243 244@itemize @bullet 245 246@item 247allocation of or sending messages to arbitrary objects; 248 249@item 250allocation of or sending messages to objects whose classes have a 251category implemented in the same file; 252 253@item 254sending messages to Objective-C constant strings (@code{@@"this is a 255constant string"}); 256 257@end itemize 258 259You should make no assumptions about receiving @code{+load} in sibling 260classes when you write @code{+load} of a class. The order in which 261sibling classes receive @code{+load} is not guaranteed. 262 263The order in which @code{+load} and @code{+initialize} are called could 264be problematic if this matters. If you don't allocate objects inside 265@code{+load}, it is guaranteed that @code{+load} is called before 266@code{+initialize}. If you create an object inside @code{+load} the 267@code{+initialize} method of object's class is invoked even if 268@code{+load} was not invoked. Note if you explicitly call @code{+load} 269on a class, @code{+initialize} will be called first. To avoid possible 270problems try to implement only one of these methods. 271 272The @code{+load} method is also invoked when a bundle is dynamically 273loaded into your running program. This happens automatically without any 274intervening operation from you. When you write bundles and you need to 275write @code{+load} you can safely create and send messages to objects whose 276classes already exist in the running program. The same restrictions as 277above apply to classes defined in bundle. 278 279 280 281@node Type encoding 282@section Type Encoding 283 284This is an advanced section. Type encodings are used extensively by 285the compiler and by the runtime, but you generally do not need to know 286about them to use Objective-C. 287 288The Objective-C compiler generates type encodings for all the types. 289These type encodings are used at runtime to find out information about 290selectors and methods and about objects and classes. 291 292The types are encoded in the following way: 293 294@c @sp 1 295 296@multitable @columnfractions .25 .75 297@item @code{_Bool} 298@tab @code{B} 299@item @code{char} 300@tab @code{c} 301@item @code{unsigned char} 302@tab @code{C} 303@item @code{short} 304@tab @code{s} 305@item @code{unsigned short} 306@tab @code{S} 307@item @code{int} 308@tab @code{i} 309@item @code{unsigned int} 310@tab @code{I} 311@item @code{long} 312@tab @code{l} 313@item @code{unsigned long} 314@tab @code{L} 315@item @code{long long} 316@tab @code{q} 317@item @code{unsigned long long} 318@tab @code{Q} 319@item @code{float} 320@tab @code{f} 321@item @code{double} 322@tab @code{d} 323@item @code{long double} 324@tab @code{D} 325@item @code{void} 326@tab @code{v} 327@item @code{id} 328@tab @code{@@} 329@item @code{Class} 330@tab @code{#} 331@item @code{SEL} 332@tab @code{:} 333@item @code{char*} 334@tab @code{*} 335@item @code{enum} 336@tab an @code{enum} is encoded exactly as the integer type that the compiler uses for it, which depends on the enumeration 337values. Often the compiler users @code{unsigned int}, which is then encoded as @code{I}. 338@item unknown type 339@tab @code{?} 340@item Complex types 341@tab @code{j} followed by the inner type. For example @code{_Complex double} is encoded as "jd". 342@item bit-fields 343@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) 344@end multitable 345 346@c @sp 1 347 348The encoding of bit-fields has changed to allow bit-fields to be 349properly handled by the runtime functions that compute sizes and 350alignments of types that contain bit-fields. The previous encoding 351contained only the size of the bit-field. Using only this information 352it is not possible to reliably compute the size occupied by the 353bit-field. This is very important in the presence of the Boehm's 354garbage collector because the objects are allocated using the typed 355memory facility available in this collector. The typed memory 356allocation requires information about where the pointers are located 357inside the object. 358 359The position in the bit-field is the position, counting in bits, of the 360bit closest to the beginning of the structure. 361 362The non-atomic types are encoded as follows: 363 364@c @sp 1 365 366@multitable @columnfractions .2 .8 367@item pointers 368@tab @samp{^} followed by the pointed type. 369@item arrays 370@tab @samp{[} followed by the number of elements in the array followed by the type of the elements followed by @samp{]} 371@item structures 372@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{@}} 373@item unions 374@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{)} 375@item vectors 376@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{]} 377@end multitable 378 379Here are some types and their encodings, as they are generated by the 380compiler on an i386 machine: 381 382@sp 1 383 384@multitable @columnfractions .60 .40 385@item Objective-C type 386@tab Compiler encoding 387@item 388@smallexample 389int a[10]; 390@end smallexample 391@tab @code{[10i]} 392@item 393@smallexample 394struct @{ 395 int i; 396 float f[3]; 397 int a:3; 398 int b:2; 399 char c; 400@} 401@end smallexample 402@tab @code{@{?=i[3f]b128i3b131i2c@}} 403@item 404@smallexample 405int a __attribute__ ((vector_size (16))); 406@end smallexample 407@tab @code{![16,16i]} (alignment depends on the machine) 408@end multitable 409 410@sp 1 411 412In addition to the types the compiler also encodes the type 413specifiers. The table below describes the encoding of the current 414Objective-C type specifiers: 415 416@sp 1 417 418@multitable @columnfractions .25 .75 419@item Specifier 420@tab Encoding 421@item @code{const} 422@tab @code{r} 423@item @code{in} 424@tab @code{n} 425@item @code{inout} 426@tab @code{N} 427@item @code{out} 428@tab @code{o} 429@item @code{bycopy} 430@tab @code{O} 431@item @code{byref} 432@tab @code{R} 433@item @code{oneway} 434@tab @code{V} 435@end multitable 436 437@sp 1 438 439The type specifiers are encoded just before the type. Unlike types 440however, the type specifiers are only encoded when they appear in method 441argument types. 442 443Note how @code{const} interacts with pointers: 444 445@sp 1 446 447@multitable @columnfractions .25 .75 448@item Objective-C type 449@tab Compiler encoding 450@item 451@smallexample 452const int 453@end smallexample 454@tab @code{ri} 455@item 456@smallexample 457const int* 458@end smallexample 459@tab @code{^ri} 460@item 461@smallexample 462int *const 463@end smallexample 464@tab @code{r^i} 465@end multitable 466 467@sp 1 468 469@code{const int*} is a pointer to a @code{const int}, and so is 470encoded as @code{^ri}. @code{int* const}, instead, is a @code{const} 471pointer to an @code{int}, and so is encoded as @code{r^i}. 472 473Finally, there is a complication when encoding @code{const char *} 474versus @code{char * const}. Because @code{char *} is encoded as 475@code{*} and not as @code{^c}, there is no way to express the fact 476that @code{r} applies to the pointer or to the pointee. 477 478Hence, it is assumed as a convention that @code{r*} means @code{const 479char *} (since it is what is most often meant), and there is no way to 480encode @code{char *const}. @code{char *const} would simply be encoded 481as @code{*}, and the @code{const} is lost. 482 483@menu 484* Legacy type encoding:: 485* @@encode:: 486* Method signatures:: 487@end menu 488 489@node Legacy type encoding 490@subsection Legacy Type Encoding 491 492Unfortunately, historically GCC used to have a number of bugs in its 493encoding code. The NeXT runtime expects GCC to emit type encodings in 494this historical format (compatible with GCC-3.3), so when using the 495NeXT runtime, GCC will introduce on purpose a number of incorrect 496encodings: 497 498@itemize @bullet 499 500@item 501the read-only qualifier of the pointee gets emitted before the '^'. 502The read-only qualifier of the pointer itself gets ignored, unless it 503is a typedef. Also, the 'r' is only emitted for the outermost type. 504 505@item 50632-bit longs are encoded as 'l' or 'L', but not always. For typedefs, 507the compiler uses 'i' or 'I' instead if encoding a struct field or a 508pointer. 509 510@item 511@code{enum}s are always encoded as 'i' (int) even if they are actually 512unsigned or long. 513 514@end itemize 515 516In addition to that, the NeXT runtime uses a different encoding for 517bitfields. It encodes them as @code{b} followed by the size, without 518a bit offset or the underlying field type. 519 520@node @@encode 521@subsection @code{@@encode} 522 523GNU Objective-C supports the @code{@@encode} syntax that allows you to 524create a type encoding from a C/Objective-C type. For example, 525@code{@@encode(int)} is compiled by the compiler into @code{"i"}. 526 527@code{@@encode} does not support type qualifiers other than 528@code{const}. For example, @code{@@encode(const char*)} is valid and 529is compiled into @code{"r*"}, while @code{@@encode(bycopy char *)} is 530invalid and will cause a compilation error. 531 532@node Method signatures 533@subsection Method Signatures 534 535This section documents the encoding of method types, which is rarely 536needed to use Objective-C. You should skip it at a first reading; the 537runtime provides functions that will work on methods and can walk 538through the list of parameters and interpret them for you. These 539functions are part of the public ``API'' and are the preferred way to 540interact with method signatures from user code. 541 542But if you need to debug a problem with method signatures and need to 543know how they are implemented (i.e., the ``ABI''), read on. 544 545Methods have their ``signature'' encoded and made available to the 546runtime. The ``signature'' encodes all the information required to 547dynamically build invocations of the method at runtime: return type 548and arguments. 549 550The ``signature'' is a null-terminated string, composed of the following: 551 552@itemize @bullet 553 554@item 555The return type, including type qualifiers. For example, a method 556returning @code{int} would have @code{i} here. 557 558@item 559The total size (in bytes) required to pass all the parameters. This 560includes the two hidden parameters (the object @code{self} and the 561method selector @code{_cmd}). 562 563@item 564Each argument, with the type encoding, followed by the offset (in 565bytes) of the argument in the list of parameters. 566 567@end itemize 568 569For example, a method with no arguments and returning @code{int} would 570have the signature @code{i8@@0:4} if the size of a pointer is 4. The 571signature is interpreted as follows: the @code{i} is the return type 572(an @code{int}), the @code{8} is the total size of the parameters in 573bytes (two pointers each of size 4), the @code{@@0} is the first 574parameter (an object at byte offset @code{0}) and @code{:4} is the 575second parameter (a @code{SEL} at byte offset @code{4}). 576 577You can easily find more examples by running the ``strings'' program 578on an Objective-C object file compiled by GCC. You'll see a lot of 579strings that look very much like @code{i8@@0:4}. They are signatures 580of Objective-C methods. 581 582 583@node Garbage Collection 584@section Garbage Collection 585 586This section is specific for the GNU Objective-C runtime. If you are 587using a different runtime, you can skip it. 588 589Support for garbage collection with the GNU runtime has been added by 590using a powerful conservative garbage collector, known as the 591Boehm-Demers-Weiser conservative garbage collector. 592 593To enable the support for it you have to configure the compiler using 594an additional argument, @w{@option{--enable-objc-gc}}. This will 595build the boehm-gc library, and build an additional runtime library 596which has several enhancements to support the garbage collector. The 597new library has a new name, @file{libobjc_gc.a} to not conflict with 598the non-garbage-collected library. 599 600When the garbage collector is used, the objects are allocated using the 601so-called typed memory allocation mechanism available in the 602Boehm-Demers-Weiser collector. This mode requires precise information on 603where pointers are located inside objects. This information is computed 604once per class, immediately after the class has been initialized. 605 606There is a new runtime function @code{class_ivar_set_gcinvisible()} 607which can be used to declare a so-called @dfn{weak pointer} 608reference. Such a pointer is basically hidden for the garbage collector; 609this can be useful in certain situations, especially when you want to 610keep track of the allocated objects, yet allow them to be 611collected. This kind of pointers can only be members of objects, you 612cannot declare a global pointer as a weak reference. Every type which is 613a pointer type can be declared a weak pointer, including @code{id}, 614@code{Class} and @code{SEL}. 615 616Here is an example of how to use this feature. Suppose you want to 617implement a class whose instances hold a weak pointer reference; the 618following class does this: 619 620@smallexample 621 622@@interface WeakPointer : Object 623@{ 624 const void* weakPointer; 625@} 626 627- initWithPointer:(const void*)p; 628- (const void*)weakPointer; 629@@end 630 631 632@@implementation WeakPointer 633 634+ (void)initialize 635@{ 636 if (self == objc_lookUpClass ("WeakPointer")) 637 class_ivar_set_gcinvisible (self, "weakPointer", YES); 638@} 639 640- initWithPointer:(const void*)p 641@{ 642 weakPointer = p; 643 return self; 644@} 645 646- (const void*)weakPointer 647@{ 648 return weakPointer; 649@} 650 651@@end 652 653@end smallexample 654 655Weak pointers are supported through a new type character specifier 656represented by the @samp{!} character. The 657@code{class_ivar_set_gcinvisible()} function adds or removes this 658specifier to the string type description of the instance variable named 659as argument. 660 661@c ========================================================================= 662@node Constant string objects 663@section Constant String Objects 664 665GNU Objective-C provides constant string objects that are generated 666directly by the compiler. You declare a constant string object by 667prefixing a C constant string with the character @samp{@@}: 668 669@smallexample 670 id myString = @@"this is a constant string object"; 671@end smallexample 672 673The constant string objects are by default instances of the 674@code{NXConstantString} class which is provided by the GNU Objective-C 675runtime. To get the definition of this class you must include the 676@file{objc/NXConstStr.h} header file. 677 678User defined libraries may want to implement their own constant string 679class. To be able to support them, the GNU Objective-C compiler provides 680a new command line options @option{-fconstant-string-class=@var{class-name}}. 681The provided class should adhere to a strict structure, the same 682as @code{NXConstantString}'s structure: 683 684@smallexample 685 686@@interface MyConstantStringClass 687@{ 688 Class isa; 689 char *c_string; 690 unsigned int len; 691@} 692@@end 693 694@end smallexample 695 696@code{NXConstantString} inherits from @code{Object}; user class 697libraries may choose to inherit the customized constant string class 698from a different class than @code{Object}. There is no requirement in 699the methods the constant string class has to implement, but the final 700ivar layout of the class must be the compatible with the given 701structure. 702 703When the compiler creates the statically allocated constant string 704object, the @code{c_string} field will be filled by the compiler with 705the string; the @code{length} field will be filled by the compiler with 706the string length; the @code{isa} pointer will be filled with 707@code{NULL} by the compiler, and it will later be fixed up automatically 708at runtime by the GNU Objective-C runtime library to point to the class 709which was set by the @option{-fconstant-string-class} option when the 710object file is loaded (if you wonder how it works behind the scenes, the 711name of the class to use, and the list of static objects to fixup, are 712stored by the compiler in the object file in a place where the GNU 713runtime library will find them at runtime). 714 715As a result, when a file is compiled with the 716@option{-fconstant-string-class} option, all the constant string objects 717will be instances of the class specified as argument to this option. It 718is possible to have multiple compilation units referring to different 719constant string classes, neither the compiler nor the linker impose any 720restrictions in doing this. 721 722@c ========================================================================= 723@node compatibility_alias 724@section @code{compatibility_alias} 725 726The keyword @code{@@compatibility_alias} allows you to define a class name 727as equivalent to another class name. For example: 728 729@smallexample 730@@compatibility_alias WOApplication GSWApplication; 731@end smallexample 732 733tells the compiler that each time it encounters @code{WOApplication} as 734a class name, it should replace it with @code{GSWApplication} (that is, 735@code{WOApplication} is just an alias for @code{GSWApplication}). 736 737There are some constraints on how this can be used--- 738 739@itemize @bullet 740 741@item @code{WOApplication} (the alias) must not be an existing class; 742 743@item @code{GSWApplication} (the real class) must be an existing class. 744 745@end itemize 746 747@c ========================================================================= 748@node Exceptions 749@section Exceptions 750 751GNU Objective-C provides exception support built into the language, as 752in the following example: 753 754@smallexample 755 @@try @{ 756 @dots{} 757 @@throw expr; 758 @dots{} 759 @} 760 @@catch (AnObjCClass *exc) @{ 761 @dots{} 762 @@throw expr; 763 @dots{} 764 @@throw; 765 @dots{} 766 @} 767 @@catch (AnotherClass *exc) @{ 768 @dots{} 769 @} 770 @@catch (id allOthers) @{ 771 @dots{} 772 @} 773 @@finally @{ 774 @dots{} 775 @@throw expr; 776 @dots{} 777 @} 778@end smallexample 779 780The @code{@@throw} statement may appear anywhere in an Objective-C or 781Objective-C++ program; when used inside of a @code{@@catch} block, the 782@code{@@throw} may appear without an argument (as shown above), in 783which case the object caught by the @code{@@catch} will be rethrown. 784 785Note that only (pointers to) Objective-C objects may be thrown and 786caught using this scheme. When an object is thrown, it will be caught 787by the nearest @code{@@catch} clause capable of handling objects of 788that type, analogously to how @code{catch} blocks work in C++ and 789Java. A @code{@@catch(id @dots{})} clause (as shown above) may also 790be provided to catch any and all Objective-C exceptions not caught by 791previous @code{@@catch} clauses (if any). 792 793The @code{@@finally} clause, if present, will be executed upon exit 794from the immediately preceding @code{@@try @dots{} @@catch} section. 795This will happen regardless of whether any exceptions are thrown, 796caught or rethrown inside the @code{@@try @dots{} @@catch} section, 797analogously to the behavior of the @code{finally} clause in Java. 798 799There are several caveats to using the new exception mechanism: 800 801@itemize @bullet 802@item 803The @option{-fobjc-exceptions} command line option must be used when 804compiling Objective-C files that use exceptions. 805 806@item 807With the GNU runtime, exceptions are always implemented as ``native'' 808exceptions and it is recommended that the @option{-fexceptions} and 809@option{-shared-libgcc} options are used when linking. 810 811@item 812With the NeXT runtime, although currently designed to be binary 813compatible with @code{NS_HANDLER}-style idioms provided by the 814@code{NSException} class, the new exceptions can only be used on Mac 815OS X 10.3 (Panther) and later systems, due to additional functionality 816needed in the NeXT Objective-C runtime. 817 818@item 819As mentioned above, the new exceptions do not support handling 820types other than Objective-C objects. Furthermore, when used from 821Objective-C++, the Objective-C exception model does not interoperate with C++ 822exceptions at this time. This means you cannot @code{@@throw} an exception 823from Objective-C and @code{catch} it in C++, or vice versa 824(i.e., @code{throw @dots{} @@catch}). 825@end itemize 826 827@c ========================================================================= 828@node Synchronization 829@section Synchronization 830 831GNU Objective-C provides support for synchronized blocks: 832 833@smallexample 834 @@synchronized (ObjCClass *guard) @{ 835 @dots{} 836 @} 837@end smallexample 838 839Upon entering the @code{@@synchronized} block, a thread of execution 840shall first check whether a lock has been placed on the corresponding 841@code{guard} object by another thread. If it has, the current thread 842shall wait until the other thread relinquishes its lock. Once 843@code{guard} becomes available, the current thread will place its own 844lock on it, execute the code contained in the @code{@@synchronized} 845block, and finally relinquish the lock (thereby making @code{guard} 846available to other threads). 847 848Unlike Java, Objective-C does not allow for entire methods to be 849marked @code{@@synchronized}. Note that throwing exceptions out of 850@code{@@synchronized} blocks is allowed, and will cause the guarding 851object to be unlocked properly. 852 853Because of the interactions between synchronization and exception 854handling, you can only use @code{@@synchronized} when compiling with 855exceptions enabled, that is with the command line option 856@option{-fobjc-exceptions}. 857 858 859@c ========================================================================= 860@node Fast enumeration 861@section Fast Enumeration 862 863@menu 864* Using fast enumeration:: 865* c99-like fast enumeration syntax:: 866* Fast enumeration details:: 867* Fast enumeration protocol:: 868@end menu 869 870@c ================================ 871@node Using fast enumeration 872@subsection Using Fast Enumeration 873 874GNU Objective-C provides support for the fast enumeration syntax: 875 876@smallexample 877 id array = @dots{}; 878 id object; 879 880 for (object in array) 881 @{ 882 /* Do something with 'object' */ 883 @} 884@end smallexample 885 886@code{array} needs to be an Objective-C object (usually a collection 887object, for example an array, a dictionary or a set) which implements 888the ``Fast Enumeration Protocol'' (see below). If you are using a 889Foundation library such as GNUstep Base or Apple Cocoa Foundation, all 890collection objects in the library implement this protocol and can be 891used in this way. 892 893The code above would iterate over all objects in @code{array}. For 894each of them, it assigns it to @code{object}, then executes the 895@code{Do something with 'object'} statements. 896 897Here is a fully worked-out example using a Foundation library (which 898provides the implementation of @code{NSArray}, @code{NSString} and 899@code{NSLog}): 900 901@smallexample 902 NSArray *array = [NSArray arrayWithObjects: @@"1", @@"2", @@"3", nil]; 903 NSString *object; 904 905 for (object in array) 906 NSLog (@@"Iterating over %@@", object); 907@end smallexample 908 909 910@c ================================ 911@node c99-like fast enumeration syntax 912@subsection C99-Like Fast Enumeration Syntax 913 914A c99-like declaration syntax is also allowed: 915 916@smallexample 917 id array = @dots{}; 918 919 for (id object in array) 920 @{ 921 /* Do something with 'object' */ 922 @} 923@end smallexample 924 925this is completely equivalent to: 926 927@smallexample 928 id array = @dots{}; 929 930 @{ 931 id object; 932 for (object in array) 933 @{ 934 /* Do something with 'object' */ 935 @} 936 @} 937@end smallexample 938 939but can save some typing. 940 941Note that the option @option{-std=c99} is not required to allow this 942syntax in Objective-C. 943 944@c ================================ 945@node Fast enumeration details 946@subsection Fast Enumeration Details 947 948Here is a more technical description with the gory details. Consider the code 949 950@smallexample 951 for (@var{object expression} in @var{collection expression}) 952 @{ 953 @var{statements} 954 @} 955@end smallexample 956 957here is what happens when you run it: 958 959@itemize @bullet 960@item 961@code{@var{collection expression}} is evaluated exactly once and the 962result is used as the collection object to iterate over. This means 963it is safe to write code such as @code{for (object in [NSDictionary 964keyEnumerator]) @dots{}}. 965 966@item 967the iteration is implemented by the compiler by repeatedly getting 968batches of objects from the collection object using the fast 969enumeration protocol (see below), then iterating over all objects in 970the batch. This is faster than a normal enumeration where objects are 971retrieved one by one (hence the name ``fast enumeration''). 972 973@item 974if there are no objects in the collection, then 975@code{@var{object expression}} is set to @code{nil} and the loop 976immediately terminates. 977 978@item 979if there are objects in the collection, then for each object in the 980collection (in the order they are returned) @code{@var{object expression}} 981is set to the object, then @code{@var{statements}} are executed. 982 983@item 984@code{@var{statements}} can contain @code{break} and @code{continue} 985commands, which will abort the iteration or skip to the next loop 986iteration as expected. 987 988@item 989when the iteration ends because there are no more objects to iterate 990over, @code{@var{object expression}} is set to @code{nil}. This allows 991you to determine whether the iteration finished because a @code{break} 992command was used (in which case @code{@var{object expression}} will remain 993set to the last object that was iterated over) or because it iterated 994over all the objects (in which case @code{@var{object expression}} will be 995set to @code{nil}). 996 997@item 998@code{@var{statements}} must not make any changes to the collection 999object; if they do, it is a hard error and the fast enumeration 1000terminates by invoking @code{objc_enumerationMutation}, a runtime 1001function that normally aborts the program but which can be customized 1002by Foundation libraries via @code{objc_set_mutation_handler} to do 1003something different, such as raising an exception. 1004 1005@end itemize 1006 1007@c ================================ 1008@node Fast enumeration protocol 1009@subsection Fast Enumeration Protocol 1010 1011If you want your own collection object to be usable with fast 1012enumeration, you need to have it implement the method 1013 1014@smallexample 1015- (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state 1016 objects: (id *)objects 1017 count: (unsigned long)len; 1018@end smallexample 1019 1020where @code{NSFastEnumerationState} must be defined in your code as follows: 1021 1022@smallexample 1023typedef struct 1024@{ 1025 unsigned long state; 1026 id *itemsPtr; 1027 unsigned long *mutationsPtr; 1028 unsigned long extra[5]; 1029@} NSFastEnumerationState; 1030@end smallexample 1031 1032If no @code{NSFastEnumerationState} is defined in your code, the 1033compiler will automatically replace @code{NSFastEnumerationState *} 1034with @code{struct __objcFastEnumerationState *}, where that type is 1035silently defined by the compiler in an identical way. This can be 1036confusing and we recommend that you define 1037@code{NSFastEnumerationState} (as shown above) instead. 1038 1039The method is called repeatedly during a fast enumeration to retrieve 1040batches of objects. Each invocation of the method should retrieve the 1041next batch of objects. 1042 1043The return value of the method is the number of objects in the current 1044batch; this should not exceed @code{len}, which is the maximum size of 1045a batch as requested by the caller. The batch itself is returned in 1046the @code{itemsPtr} field of the @code{NSFastEnumerationState} struct. 1047 1048To help with returning the objects, the @code{objects} array is a C 1049array preallocated by the caller (on the stack) of size @code{len}. 1050In many cases you can put the objects you want to return in that 1051@code{objects} array, then do @code{itemsPtr = objects}. But you 1052don't have to; if your collection already has the objects to return in 1053some form of C array, it could return them from there instead. 1054 1055The @code{state} and @code{extra} fields of the 1056@code{NSFastEnumerationState} structure allows your collection object 1057to keep track of the state of the enumeration. In a simple array 1058implementation, @code{state} may keep track of the index of the last 1059object that was returned, and @code{extra} may be unused. 1060 1061The @code{mutationsPtr} field of the @code{NSFastEnumerationState} is 1062used to keep track of mutations. It should point to a number; before 1063working on each object, the fast enumeration loop will check that this 1064number has not changed. If it has, a mutation has happened and the 1065fast enumeration will abort. So, @code{mutationsPtr} could be set to 1066point to some sort of version number of your collection, which is 1067increased by one every time there is a change (for example when an 1068object is added or removed). Or, if you are content with less strict 1069mutation checks, it could point to the number of objects in your 1070collection or some other value that can be checked to perform an 1071approximate check that the collection has not been mutated. 1072 1073Finally, note how we declared the @code{len} argument and the return 1074value to be of type @code{unsigned long}. They could also be declared 1075to be of type @code{unsigned int} and everything would still work. 1076 1077@c ========================================================================= 1078@node Messaging with the GNU Objective-C runtime 1079@section Messaging with the GNU Objective-C Runtime 1080 1081This section is specific for the GNU Objective-C runtime. If you are 1082using a different runtime, you can skip it. 1083 1084The implementation of messaging in the GNU Objective-C runtime is 1085designed to be portable, and so is based on standard C. 1086 1087Sending a message in the GNU Objective-C runtime is composed of two 1088separate steps. First, there is a call to the lookup function, 1089@code{objc_msg_lookup ()} (or, in the case of messages to super, 1090@code{objc_msg_lookup_super ()}). This runtime function takes as 1091argument the receiver and the selector of the method to be called; it 1092returns the @code{IMP}, that is a pointer to the function implementing 1093the method. The second step of method invocation consists of casting 1094this pointer function to the appropriate function pointer type, and 1095calling the function pointed to it with the right arguments. 1096 1097For example, when the compiler encounters a method invocation such as 1098@code{[object init]}, it compiles it into a call to 1099@code{objc_msg_lookup (object, @@selector(init))} followed by a cast 1100of the returned value to the appropriate function pointer type, and 1101then it calls it. 1102 1103@menu 1104* Dynamically registering methods:: 1105* Forwarding hook:: 1106@end menu 1107 1108@c ========================================================================= 1109@node Dynamically registering methods 1110@subsection Dynamically Registering Methods 1111 1112If @code{objc_msg_lookup()} does not find a suitable method 1113implementation, because the receiver does not implement the required 1114method, it tries to see if the class can dynamically register the 1115method. 1116 1117To do so, the runtime checks if the class of the receiver implements 1118the method 1119 1120@smallexample 1121+ (BOOL) resolveInstanceMethod: (SEL)selector; 1122@end smallexample 1123 1124in the case of an instance method, or 1125 1126@smallexample 1127+ (BOOL) resolveClassMethod: (SEL)selector; 1128@end smallexample 1129 1130in the case of a class method. If the class implements it, the 1131runtime invokes it, passing as argument the selector of the original 1132method, and if it returns @code{YES}, the runtime tries the lookup 1133again, which could now succeed if a matching method was added 1134dynamically by @code{+resolveInstanceMethod:} or 1135@code{+resolveClassMethod:}. 1136 1137This allows classes to dynamically register methods (by adding them to 1138the class using @code{class_addMethod}) when they are first called. 1139To do so, a class should implement @code{+resolveInstanceMethod:} (or, 1140depending on the case, @code{+resolveClassMethod:}) and have it 1141recognize the selectors of methods that can be registered dynamically 1142at runtime, register them, and return @code{YES}. It should return 1143@code{NO} for methods that it does not dynamically registered at 1144runtime. 1145 1146If @code{+resolveInstanceMethod:} (or @code{+resolveClassMethod:}) is 1147not implemented or returns @code{NO}, the runtime then tries the 1148forwarding hook. 1149 1150Support for @code{+resolveInstanceMethod:} and 1151@code{resolveClassMethod:} was added to the GNU Objective-C runtime in 1152GCC version 4.6. 1153 1154@c ========================================================================= 1155@node Forwarding hook 1156@subsection Forwarding Hook 1157 1158The GNU Objective-C runtime provides a hook, called 1159@code{__objc_msg_forward2}, which is called by 1160@code{objc_msg_lookup()} when it cannot find a method implementation in 1161the runtime tables and after calling @code{+resolveInstanceMethod:} 1162and @code{+resolveClassMethod:} has been attempted and did not succeed 1163in dynamically registering the method. 1164 1165To configure the hook, you set the global variable 1166@code{__objc_msg_forward2} to a function with the same argument and 1167return types of @code{objc_msg_lookup()}. When 1168@code{objc_msg_lookup()} cannot find a method implementation, it 1169invokes the hook function you provided to get a method implementation 1170to return. So, in practice @code{__objc_msg_forward2} allows you to 1171extend @code{objc_msg_lookup()} by adding some custom code that is 1172called to do a further lookup when no standard method implementation 1173can be found using the normal lookup. 1174 1175This hook is generally reserved for ``Foundation'' libraries such as 1176GNUstep Base, which use it to implement their high-level method 1177forwarding API, typically based around the @code{forwardInvocation:} 1178method. So, unless you are implementing your own ``Foundation'' 1179library, you should not set this hook. 1180 1181In a typical forwarding implementation, the @code{__objc_msg_forward2} 1182hook function determines the argument and return type of the method 1183that is being looked up, and then creates a function that takes these 1184arguments and has that return type, and returns it to the caller. 1185Creating this function is non-trivial and is typically performed using 1186a dedicated library such as @code{libffi}. 1187 1188The forwarding method implementation thus created is returned by 1189@code{objc_msg_lookup()} and is executed as if it was a normal method 1190implementation. When the forwarding method implementation is called, 1191it is usually expected to pack all arguments into some sort of object 1192(typically, an @code{NSInvocation} in a ``Foundation'' library), and 1193hand it over to the programmer (@code{forwardInvocation:}) who is then 1194allowed to manipulate the method invocation using a high-level API 1195provided by the ``Foundation'' library. For example, the programmer 1196may want to examine the method invocation arguments and name and 1197potentially change them before forwarding the method invocation to one 1198or more local objects (@code{performInvocation:}) or even to remote 1199objects (by using Distributed Objects or some other mechanism). When 1200all this completes, the return value is passed back and must be 1201returned correctly to the original caller. 1202 1203Note that the GNU Objective-C runtime currently provides no support 1204for method forwarding or method invocations other than the 1205@code{__objc_msg_forward2} hook. 1206 1207If the forwarding hook does not exist or returns @code{NULL}, the 1208runtime currently attempts forwarding using an older, deprecated API, 1209and if that fails, it aborts the program. In future versions of the 1210GNU Objective-C runtime, the runtime will immediately abort. 1211