xref: /netbsd/external/gpl3/gcc.old/dist/gcc/doc/objc.texi (revision ec02198a)
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