Merge branch 'vendor/GCC50' - gcc 5.0 snapshot 1 FEB 2015
[dragonfly.git] / contrib / gcc-5.0 / gcc / doc / objc.texi
1 @c Copyright (C) 1988-2015 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
10 This document is meant to describe some of the GNU Objective-C
11 features.  It is not intended to teach you Objective-C.  There are
12 several 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
31 This section is specific for the GNU Objective-C runtime.  If you are
32 using a different runtime, you can skip it.
33
34 The GNU Objective-C runtime provides an API that allows you to
35 interact with the Objective-C runtime system, querying the live
36 runtime structures and even manipulating them.  This allows you for
37 example to inspect and navigate classes, methods and protocols; to
38 define new classes or new methods, and even to modify existing classes
39 or protocols.
40
41 If you are using a ``Foundation'' library such as GNUstep-Base, this
42 library will provide you with a rich set of functionality to do most
43 of the inspection tasks, and you probably will only need direct access
44 to 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
55 The GNU Objective-C runtime provides an API which is similar to the
56 one provided by the ``Objective-C 2.0'' Apple/NeXT Objective-C
57 runtime.  The API is documented in the public header files of the GNU
58 Objective-C runtime:
59
60 @itemize @bullet
61
62 @item
63 @file{objc/objc.h}: this is the basic Objective-C header file,
64 defining the basic Objective-C types such as @code{id}, @code{Class}
65 and @code{BOOL}.  You have to include this header to do almost
66 anything with Objective-C.
67
68 @item
69 @file{objc/runtime.h}: this header declares most of the public runtime
70 API functions allowing you to inspect and manipulate the Objective-C
71 runtime data structures.  These functions are fairly standardized
72 across Objective-C runtimes and are almost identical to the Apple/NeXT
73 Objective-C runtime ones.  It does not declare functions in some
74 specialized areas (constructing and forwarding message invocations,
75 threading) 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
77 functions, 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
82 construct, deconstruct and forward message invocations.  Because
83 messaging is done in quite a different way on different runtimes,
84 functions in this header are specific to the GNU Objective-C runtime
85 implementation.
86
87 @item
88 @file{objc/objc-exception.h}: this header declares some public
89 functions related to Objective-C exceptions.  For example functions in
90 this header allow you to throw an Objective-C exception from plain
91 C/C++ code.
92
93 @item
94 @file{objc/objc-sync.h}: this header declares some public functions
95 related to the Objective-C @code{@@synchronized()} syntax, allowing
96 you to emulate an Objective-C @code{@@synchronized()} block in plain
97 C/C++ code.
98
99 @item
100 @file{objc/thr.h}: this header declares a public runtime API threading
101 layer that is only provided by the GNU Objective-C runtime.  It
102 declares functions such as @code{objc_mutex_lock()}, which provide a
103 platform-independent set of threading functions.
104
105 @end itemize
106
107 The header files contain detailed documentation for each function in
108 the 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
114 The GNU Objective-C runtime used to provide a different API, which we
115 call the ``traditional'' GNU Objective-C runtime API.  Functions
116 belonging to this API are easy to recognize because they use a
117 different naming convention, such as @code{class_get_super_class()}
118 (traditional API) instead of @code{class_getSuperclass()} (modern
119 API).  Software using this API includes the file
120 @file{objc/objc-api.h} where it is declared.
121
122 Starting with GCC 4.7.0, the traditional GNU runtime API is no longer
123 available.
124
125 @c =========================================================================
126 @node Executing code before main
127 @section @code{+load}: Executing code before main
128
129 This section is specific for the GNU Objective-C runtime.  If you are
130 using a different runtime, you can skip it.
131
132 The GNU Objective-C runtime provides a way that allows you to execute
133 code before the execution of the program enters the @code{main}
134 function.  The code is executed on a per-class and a per-category basis,
135 through a special class method @code{+load}.
136
137 This facility is very useful if you want to initialize global variables
138 which can be accessed by the program directly, without sending a message
139 to 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
142 class object, which in some cases could be too late.
143
144 Suppose for example you have a @code{FileStream} class that declares
145 @code{Stdin}, @code{Stdout} and @code{Stderr} as global variables, like
146 below:
147
148 @smallexample
149
150 FileStream *Stdin = nil;
151 FileStream *Stdout = nil;
152 FileStream *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
168 In this example, the initialization of @code{Stdin}, @code{Stdout} and
169 @code{Stderr} in @code{+initialize} occurs too late.  The programmer can
170 send a message to one of these objects before the variables are actually
171 initialized, thus sending messages to the @code{nil} object.  The
172 @code{+initialize} method which actually initializes the global
173 variables is not invoked until the first message is sent to the class
174 object.  The solution would require these variables to be initialized
175 just before entering @code{main}.
176
177 The correct solution of the above problem is to use the @code{+load}
178 method 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
196 The @code{+load} is a method that is not overridden by categories.  If a
197 class and a category of it both implement @code{+load}, both methods are
198 invoked.  This allows some additional initializations to be performed in
199 a category.
200
201 This mechanism is not intended to be a replacement for @code{+initialize}.
202 You should be aware of its limitations when you decide to use it
203 instead 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 what you cannot do in @code{+load}
212
213 @code{+load} is to be used only as a last resort.  Because it is
214 executed very early, most of the Objective-C runtime machinery will
215 not be ready when @code{+load} is executed; hence @code{+load} works
216 best for executing C code that is independent on the Objective-C
217 runtime.
218
219 The @code{+load} implementation in the GNU runtime guarantees you the
220 following things:
221
222 @itemize @bullet
223
224 @item
225 you can write whatever C code you like;
226
227 @item
228 you can allocate and send messages to objects whose class is implemented
229 in the same file;
230
231 @item
232 the @code{+load} implementation of all super classes of a class are
233 executed before the @code{+load} of that class is executed;
234
235 @item
236 the @code{+load} implementation of a class is executed before the
237 @code{+load} implementation of any category.
238
239 @end itemize
240
241 In particular, the following things, even if they can work in a
242 particular case, are not guaranteed:
243
244 @itemize @bullet
245
246 @item
247 allocation of or sending messages to arbitrary objects;
248
249 @item
250 allocation of or sending messages to objects whose classes have a
251 category implemented in the same file;
252
253 @item
254 sending messages to Objective-C constant strings (@code{@@"this is a
255 constant string"});
256
257 @end itemize
258
259 You should make no assumptions about receiving @code{+load} in sibling
260 classes when you write @code{+load} of a class.  The order in which
261 sibling classes receive @code{+load} is not guaranteed.
262
263 The order in which @code{+load} and @code{+initialize} are called could
264 be 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}
269 on a class, @code{+initialize} will be called first.  To avoid possible
270 problems try to implement only one of these methods.
271
272 The @code{+load} method is also invoked when a bundle is dynamically
273 loaded into your running program.  This happens automatically without any
274 intervening operation from you.  When you write bundles and you need to
275 write @code{+load} you can safely create and send messages to objects whose
276 classes already exist in the running program.  The same restrictions as
277 above apply to classes defined in bundle.
278
279
280
281 @node Type encoding
282 @section Type encoding
283
284 This is an advanced section.  Type encodings are used extensively by
285 the compiler and by the runtime, but you generally do not need to know
286 about them to use Objective-C.
287
288 The Objective-C compiler generates type encodings for all the types.
289 These type encodings are used at runtime to find out information about
290 selectors and methods and about objects and classes.
291
292 The 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
337 values.  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
348 The encoding of bit-fields has changed to allow bit-fields to be
349 properly handled by the runtime functions that compute sizes and
350 alignments of types that contain bit-fields.  The previous encoding
351 contained only the size of the bit-field.  Using only this information
352 it is not possible to reliably compute the size occupied by the
353 bit-field.  This is very important in the presence of the Boehm's
354 garbage collector because the objects are allocated using the typed
355 memory facility available in this collector.  The typed memory
356 allocation requires information about where the pointers are located
357 inside the object.
358
359 The position in the bit-field is the position, counting in bits, of the
360 bit closest to the beginning of the structure.
361
362 The 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
379 Here are some types and their encodings, as they are generated by the
380 compiler on an i386 machine:
381
382 @sp 1
383
384 @multitable @columnfractions .25 .75
385 @item Objective-C type
386 @tab Compiler encoding
387 @item
388 @smallexample
389 int a[10];
390 @end smallexample
391 @tab @code{[10i]}
392 @item
393 @smallexample
394 struct @{
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
405 int a __attribute__ ((vector_size (16)));
406 @end smallexample
407 @tab @code{![16,16i]} (alignment would depend on the machine)
408 @end multitable
409
410 @sp 1
411
412 In addition to the types the compiler also encodes the type
413 specifiers.  The table below describes the encoding of the current
414 Objective-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
439 The type specifiers are encoded just before the type.  Unlike types
440 however, the type specifiers are only encoded when they appear in method
441 argument types.
442
443 Note 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
452 const int
453 @end smallexample
454 @tab @code{ri}
455 @item
456 @smallexample
457 const int*
458 @end smallexample
459 @tab @code{^ri}
460 @item
461 @smallexample
462 int *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
470 encoded as @code{^ri}.  @code{int* const}, instead, is a @code{const}
471 pointer to an @code{int}, and so is encoded as @code{r^i}.
472
473 Finally, there is a complication when encoding @code{const char *}
474 versus @code{char * const}.  Because @code{char *} is encoded as
475 @code{*} and not as @code{^c}, there is no way to express the fact
476 that @code{r} applies to the pointer or to the pointee.
477
478 Hence, it is assumed as a convention that @code{r*} means @code{const
479 char *} (since it is what is most often meant), and there is no way to
480 encode @code{char *const}.  @code{char *const} would simply be encoded
481 as @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
492 Unfortunately, historically GCC used to have a number of bugs in its
493 encoding code.  The NeXT runtime expects GCC to emit type encodings in
494 this historical format (compatible with GCC-3.3), so when using the
495 NeXT runtime, GCC will introduce on purpose a number of incorrect
496 encodings:
497
498 @itemize @bullet
499
500 @item
501 the read-only qualifier of the pointee gets emitted before the '^'.
502 The read-only qualifier of the pointer itself gets ignored, unless it
503 is a typedef.  Also, the 'r' is only emitted for the outermost type.
504
505 @item
506 32-bit longs are encoded as 'l' or 'L', but not always.  For typedefs,
507 the compiler uses 'i' or 'I' instead if encoding a struct field or a
508 pointer.
509
510 @item
511 @code{enum}s are always encoded as 'i' (int) even if they are actually
512 unsigned or long.
513
514 @end itemize
515
516 In addition to that, the NeXT runtime uses a different encoding for
517 bitfields.  It encodes them as @code{b} followed by the size, without
518 a bit offset or the underlying field type.
519
520 @node @@encode
521 @subsection @@encode
522
523 GNU Objective-C supports the @code{@@encode} syntax that allows you to
524 create 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
529 is compiled into @code{"r*"}, while @code{@@encode(bycopy char *)} is
530 invalid and will cause a compilation error.
531
532 @node Method signatures
533 @subsection Method signatures
534
535 This section documents the encoding of method types, which is rarely
536 needed to use Objective-C.  You should skip it at a first reading; the
537 runtime provides functions that will work on methods and can walk
538 through the list of parameters and interpret them for you.  These
539 functions are part of the public ``API'' and are the preferred way to
540 interact with method signatures from user code.
541
542 But if you need to debug a problem with method signatures and need to
543 know how they are implemented (i.e., the ``ABI''), read on.
544
545 Methods have their ``signature'' encoded and made available to the
546 runtime.  The ``signature'' encodes all the information required to
547 dynamically build invocations of the method at runtime: return type
548 and arguments.
549
550 The ``signature'' is a null-terminated string, composed of the following:
551
552 @itemize @bullet
553
554 @item
555 The return type, including type qualifiers.  For example, a method
556 returning @code{int} would have @code{i} here.
557
558 @item
559 The total size (in bytes) required to pass all the parameters.  This
560 includes the two hidden parameters (the object @code{self} and the
561 method selector @code{_cmd}).
562
563 @item
564 Each argument, with the type encoding, followed by the offset (in
565 bytes) of the argument in the list of parameters.
566
567 @end itemize
568
569 For example, a method with no arguments and returning @code{int} would
570 have the signature @code{i8@@0:4} if the size of a pointer is 4.  The
571 signature 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
573 bytes (two pointers each of size 4), the @code{@@0} is the first
574 parameter (an object at byte offset @code{0}) and @code{:4} is the
575 second parameter (a @code{SEL} at byte offset @code{4}).
576
577 You can easily find more examples by running the ``strings'' program
578 on an Objective-C object file compiled by GCC.  You'll see a lot of
579 strings that look very much like @code{i8@@0:4}.  They are signatures
580 of Objective-C methods.
581
582
583 @node Garbage Collection
584 @section Garbage Collection
585
586 This section is specific for the GNU Objective-C runtime.  If you are
587 using a different runtime, you can skip it.
588
589 Support for garbage collection with the GNU runtime has been added by
590 using a powerful conservative garbage collector, known as the
591 Boehm-Demers-Weiser conservative garbage collector.
592
593 To enable the support for it you have to configure the compiler using
594 an additional argument, @w{@option{--enable-objc-gc}}.  This will
595 build the boehm-gc library, and build an additional runtime library
596 which has several enhancements to support the garbage collector.  The
597 new library has a new name, @file{libobjc_gc.a} to not conflict with
598 the non-garbage-collected library.
599
600 When the garbage collector is used, the objects are allocated using the
601 so-called typed memory allocation mechanism available in the
602 Boehm-Demers-Weiser collector.  This mode requires precise information on
603 where pointers are located inside objects.  This information is computed
604 once per class, immediately after the class has been initialized.
605
606 There is a new runtime function @code{class_ivar_set_gcinvisible()}
607 which can be used to declare a so-called @dfn{weak pointer}
608 reference.  Such a pointer is basically hidden for the garbage collector;
609 this can be useful in certain situations, especially when you want to
610 keep track of the allocated objects, yet allow them to be
611 collected.  This kind of pointers can only be members of objects, you
612 cannot declare a global pointer as a weak reference.  Every type which is
613 a pointer type can be declared a weak pointer, including @code{id},
614 @code{Class} and @code{SEL}.
615
616 Here is an example of how to use this feature.  Suppose you want to
617 implement a class whose instances hold a weak pointer reference; the
618 following 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
655 Weak pointers are supported through a new type character specifier
656 represented by the @samp{!} character.  The
657 @code{class_ivar_set_gcinvisible()} function adds or removes this
658 specifier to the string type description of the instance variable named
659 as argument.
660
661 @c =========================================================================
662 @node Constant string objects
663 @section Constant string objects
664
665 GNU Objective-C provides constant string objects that are generated
666 directly by the compiler.  You declare a constant string object by
667 prefixing a C constant string with the character @samp{@@}:
668
669 @smallexample
670   id myString = @@"this is a constant string object";
671 @end smallexample
672
673 The constant string objects are by default instances of the
674 @code{NXConstantString} class which is provided by the GNU Objective-C
675 runtime.  To get the definition of this class you must include the
676 @file{objc/NXConstStr.h} header file.
677
678 User defined libraries may want to implement their own constant string
679 class.  To be able to support them, the GNU Objective-C compiler provides
680 a new command line options @option{-fconstant-string-class=@var{class-name}}.
681 The provided class should adhere to a strict structure, the same
682 as @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
697 libraries may choose to inherit the customized constant string class
698 from a different class than @code{Object}.  There is no requirement in
699 the methods the constant string class has to implement, but the final
700 ivar layout of the class must be the compatible with the given
701 structure.
702
703 When the compiler creates the statically allocated constant string
704 object, the @code{c_string} field will be filled by the compiler with
705 the string; the @code{length} field will be filled by the compiler with
706 the string length; the @code{isa} pointer will be filled with
707 @code{NULL} by the compiler, and it will later be fixed up automatically
708 at runtime by the GNU Objective-C runtime library to point to the class
709 which was set by the @option{-fconstant-string-class} option when the
710 object file is loaded (if you wonder how it works behind the scenes, the
711 name of the class to use, and the list of static objects to fixup, are
712 stored by the compiler in the object file in a place where the GNU
713 runtime library will find them at runtime).
714
715 As a result, when a file is compiled with the
716 @option{-fconstant-string-class} option, all the constant string objects
717 will be instances of the class specified as argument to this option.  It
718 is possible to have multiple compilation units referring to different
719 constant string classes, neither the compiler nor the linker impose any
720 restrictions in doing this.
721
722 @c =========================================================================
723 @node compatibility_alias
724 @section compatibility_alias
725
726 The keyword @code{@@compatibility_alias} allows you to define a class name
727 as equivalent to another class name.  For example:
728
729 @smallexample
730 @@compatibility_alias WOApplication GSWApplication;
731 @end smallexample
732
733 tells the compiler that each time it encounters @code{WOApplication} as
734 a class name, it should replace it with @code{GSWApplication} (that is,
735 @code{WOApplication} is just an alias for @code{GSWApplication}).
736
737 There 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
751 GNU Objective-C provides exception support built into the language, as
752 in 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
780 The @code{@@throw} statement may appear anywhere in an Objective-C or
781 Objective-C++ program; when used inside of a @code{@@catch} block, the
782 @code{@@throw} may appear without an argument (as shown above), in
783 which case the object caught by the @code{@@catch} will be rethrown.
784
785 Note that only (pointers to) Objective-C objects may be thrown and
786 caught using this scheme.  When an object is thrown, it will be caught
787 by the nearest @code{@@catch} clause capable of handling objects of
788 that type, analogously to how @code{catch} blocks work in C++ and
789 Java.  A @code{@@catch(id @dots{})} clause (as shown above) may also
790 be provided to catch any and all Objective-C exceptions not caught by
791 previous @code{@@catch} clauses (if any).
792
793 The @code{@@finally} clause, if present, will be executed upon exit
794 from the immediately preceding @code{@@try @dots{} @@catch} section.
795 This will happen regardless of whether any exceptions are thrown,
796 caught or rethrown inside the @code{@@try @dots{} @@catch} section,
797 analogously to the behavior of the @code{finally} clause in Java.
798
799 There are several caveats to using the new exception mechanism:
800
801 @itemize @bullet
802 @item
803 The @option{-fobjc-exceptions} command line option must be used when
804 compiling Objective-C files that use exceptions.
805
806 @item
807 With the GNU runtime, exceptions are always implemented as ``native''
808 exceptions and it is recommended that the @option{-fexceptions} and
809 @option{-shared-libgcc} options are used when linking.
810
811 @item
812 With the NeXT runtime, although currently designed to be binary
813 compatible with @code{NS_HANDLER}-style idioms provided by the
814 @code{NSException} class, the new exceptions can only be used on Mac
815 OS X 10.3 (Panther) and later systems, due to additional functionality
816 needed in the NeXT Objective-C runtime.
817
818 @item
819 As mentioned above, the new exceptions do not support handling
820 types other than Objective-C objects.   Furthermore, when used from
821 Objective-C++, the Objective-C exception model does not interoperate with C++
822 exceptions at this time.  This means you cannot @code{@@throw} an exception
823 from 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
831 GNU Objective-C provides support for synchronized blocks:
832
833 @smallexample
834   @@synchronized (ObjCClass *guard) @{
835     @dots{}
836   @}
837 @end smallexample
838
839 Upon entering the @code{@@synchronized} block, a thread of execution
840 shall first check whether a lock has been placed on the corresponding
841 @code{guard} object by another thread.  If it has, the current thread
842 shall wait until the other thread relinquishes its lock.  Once
843 @code{guard} becomes available, the current thread will place its own
844 lock on it, execute the code contained in the @code{@@synchronized}
845 block, and finally relinquish the lock (thereby making @code{guard}
846 available to other threads).
847
848 Unlike Java, Objective-C does not allow for entire methods to be
849 marked @code{@@synchronized}.  Note that throwing exceptions out of
850 @code{@@synchronized} blocks is allowed, and will cause the guarding
851 object to be unlocked properly.
852
853 Because of the interactions between synchronization and exception
854 handling, you can only use @code{@@synchronized} when compiling with
855 exceptions 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
874 GNU 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
887 object, for example an array, a dictionary or a set) which implements
888 the ``Fast Enumeration Protocol'' (see below).  If you are using a
889 Foundation library such as GNUstep Base or Apple Cocoa Foundation, all
890 collection objects in the library implement this protocol and can be
891 used in this way.
892
893 The code above would iterate over all objects in @code{array}.  For
894 each of them, it assigns it to @code{object}, then executes the
895 @code{Do something with 'object'} statements.
896
897 Here is a fully worked-out example using a Foundation library (which
898 provides 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
914 A 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
925 this 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
939 but can save some typing.
940
941 Note that the option @option{-std=c99} is not required to allow this
942 syntax in Objective-C.
943
944 @c ================================
945 @node Fast enumeration details
946 @subsection Fast enumeration details
947
948 Here 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
957 here is what happens when you run it:
958
959 @itemize @bullet
960 @item
961 @code{@var{collection expression}} is evaluated exactly once and the
962 result is used as the collection object to iterate over.  This means
963 it is safe to write code such as @code{for (object in [NSDictionary
964 keyEnumerator]) @dots{}}.
965
966 @item
967 the iteration is implemented by the compiler by repeatedly getting
968 batches of objects from the collection object using the fast
969 enumeration protocol (see below), then iterating over all objects in
970 the batch.  This is faster than a normal enumeration where objects are
971 retrieved one by one (hence the name ``fast enumeration'').
972
973 @item
974 if there are no objects in the collection, then
975 @code{@var{object expression}} is set to @code{nil} and the loop
976 immediately terminates.
977
978 @item
979 if there are objects in the collection, then for each object in the
980 collection (in the order they are returned) @code{@var{object expression}}
981 is set to the object, then @code{@var{statements}} are executed.
982
983 @item
984 @code{@var{statements}} can contain @code{break} and @code{continue}
985 commands, which will abort the iteration or skip to the next loop
986 iteration as expected.
987
988 @item
989 when the iteration ends because there are no more objects to iterate
990 over, @code{@var{object expression}} is set to @code{nil}.  This allows
991 you to determine whether the iteration finished because a @code{break}
992 command was used (in which case @code{@var{object expression}} will remain
993 set to the last object that was iterated over) or because it iterated
994 over all the objects (in which case @code{@var{object expression}} will be
995 set to @code{nil}).
996
997 @item
998 @code{@var{statements}} must not make any changes to the collection
999 object; if they do, it is a hard error and the fast enumeration
1000 terminates by invoking @code{objc_enumerationMutation}, a runtime
1001 function that normally aborts the program but which can be customized
1002 by Foundation libraries via @code{objc_set_mutation_handler} to do
1003 something different, such as raising an exception.
1004
1005 @end itemize
1006
1007 @c ================================
1008 @node Fast enumeration protocol
1009 @subsection Fast enumeration protocol
1010
1011 If you want your own collection object to be usable with fast
1012 enumeration, 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
1020 where @code{NSFastEnumerationState} must be defined in your code as follows:
1021
1022 @smallexample
1023 typedef struct
1024 @{
1025   unsigned long state;
1026   id            *itemsPtr;
1027   unsigned long *mutationsPtr;
1028   unsigned long extra[5];
1029 @} NSFastEnumerationState;
1030 @end smallexample
1031
1032 If no @code{NSFastEnumerationState} is defined in your code, the
1033 compiler will automatically replace @code{NSFastEnumerationState *}
1034 with @code{struct __objcFastEnumerationState *}, where that type is
1035 silently defined by the compiler in an identical way.  This can be
1036 confusing and we recommend that you define
1037 @code{NSFastEnumerationState} (as shown above) instead.
1038
1039 The method is called repeatedly during a fast enumeration to retrieve
1040 batches of objects.  Each invocation of the method should retrieve the
1041 next batch of objects.
1042
1043 The return value of the method is the number of objects in the current
1044 batch; this should not exceed @code{len}, which is the maximum size of
1045 a batch as requested by the caller.  The batch itself is returned in
1046 the @code{itemsPtr} field of the @code{NSFastEnumerationState} struct.
1047
1048 To help with returning the objects, the @code{objects} array is a C
1049 array preallocated by the caller (on the stack) of size @code{len}.
1050 In many cases you can put the objects you want to return in that
1051 @code{objects} array, then do @code{itemsPtr = objects}.  But you
1052 don't have to; if your collection already has the objects to return in
1053 some form of C array, it could return them from there instead.
1054
1055 The @code{state} and @code{extra} fields of the
1056 @code{NSFastEnumerationState} structure allows your collection object
1057 to keep track of the state of the enumeration.  In a simple array
1058 implementation, @code{state} may keep track of the index of the last
1059 object that was returned, and @code{extra} may be unused.
1060
1061 The @code{mutationsPtr} field of the @code{NSFastEnumerationState} is
1062 used to keep track of mutations.  It should point to a number; before
1063 working on each object, the fast enumeration loop will check that this
1064 number has not changed.  If it has, a mutation has happened and the
1065 fast enumeration will abort.  So, @code{mutationsPtr} could be set to
1066 point to some sort of version number of your collection, which is
1067 increased by one every time there is a change (for example when an
1068 object is added or removed).  Or, if you are content with less strict
1069 mutation checks, it could point to the number of objects in your
1070 collection or some other value that can be checked to perform an
1071 approximate check that the collection has not been mutated.
1072
1073 Finally, note how we declared the @code{len} argument and the return
1074 value to be of type @code{unsigned long}.  They could also be declared
1075 to 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
1081 This section is specific for the GNU Objective-C runtime.  If you are
1082 using a different runtime, you can skip it.
1083
1084 The implementation of messaging in the GNU Objective-C runtime is
1085 designed to be portable, and so is based on standard C.
1086
1087 Sending a message in the GNU Objective-C runtime is composed of two
1088 separate 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
1091 argument the receiver and the selector of the method to be called; it
1092 returns the @code{IMP}, that is a pointer to the function implementing
1093 the method.  The second step of method invocation consists of casting
1094 this pointer function to the appropriate function pointer type, and
1095 calling the function pointed to it with the right arguments.
1096
1097 For 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
1100 of the returned value to the appropriate function pointer type, and
1101 then 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
1112 If @code{objc_msg_lookup()} does not find a suitable method
1113 implementation, because the receiver does not implement the required
1114 method, it tries to see if the class can dynamically register the
1115 method.
1116
1117 To do so, the runtime checks if the class of the receiver implements
1118 the method
1119
1120 @smallexample
1121 + (BOOL) resolveInstanceMethod: (SEL)selector;
1122 @end smallexample
1123
1124 in the case of an instance method, or
1125
1126 @smallexample
1127 + (BOOL) resolveClassMethod: (SEL)selector;
1128 @end smallexample
1129
1130 in the case of a class method.  If the class implements it, the
1131 runtime invokes it, passing as argument the selector of the original
1132 method, and if it returns @code{YES}, the runtime tries the lookup
1133 again, which could now succeed if a matching method was added
1134 dynamically by @code{+resolveInstanceMethod:} or
1135 @code{+resolveClassMethod:}.
1136
1137 This allows classes to dynamically register methods (by adding them to
1138 the class using @code{class_addMethod}) when they are first called.
1139 To do so, a class should implement @code{+resolveInstanceMethod:} (or,
1140 depending on the case, @code{+resolveClassMethod:}) and have it
1141 recognize the selectors of methods that can be registered dynamically
1142 at runtime, register them, and return @code{YES}.  It should return
1143 @code{NO} for methods that it does not dynamically registered at
1144 runtime.
1145
1146 If @code{+resolveInstanceMethod:} (or @code{+resolveClassMethod:}) is
1147 not implemented or returns @code{NO}, the runtime then tries the
1148 forwarding hook.
1149
1150 Support for @code{+resolveInstanceMethod:} and
1151 @code{resolveClassMethod:} was added to the GNU Objective-C runtime in
1152 GCC version 4.6.
1153
1154 @c =========================================================================
1155 @node Forwarding hook
1156 @subsection Forwarding hook
1157
1158 The GNU Objective-C runtime provides a hook, called
1159 @code{__objc_msg_forward2}, which is called by
1160 @code{objc_msg_lookup()} when it can't find a method implementation in
1161 the runtime tables and after calling @code{+resolveInstanceMethod:}
1162 and @code{+resolveClassMethod:} has been attempted and did not succeed
1163 in dynamically registering the method.
1164
1165 To configure the hook, you set the global variable
1166 @code{__objc_msg_forward2} to a function with the same argument and
1167 return types of @code{objc_msg_lookup()}.  When
1168 @code{objc_msg_lookup()} can not find a method implementation, it
1169 invokes the hook function you provided to get a method implementation
1170 to return.  So, in practice @code{__objc_msg_forward2} allows you to
1171 extend @code{objc_msg_lookup()} by adding some custom code that is
1172 called to do a further lookup when no standard method implementation
1173 can be found using the normal lookup.
1174
1175 This hook is generally reserved for ``Foundation'' libraries such as
1176 GNUstep Base, which use it to implement their high-level method
1177 forwarding API, typically based around the @code{forwardInvocation:}
1178 method.  So, unless you are implementing your own ``Foundation''
1179 library, you should not set this hook.
1180
1181 In a typical forwarding implementation, the @code{__objc_msg_forward2}
1182 hook function determines the argument and return type of the method
1183 that is being looked up, and then creates a function that takes these
1184 arguments and has that return type, and returns it to the caller.
1185 Creating this function is non-trivial and is typically performed using
1186 a dedicated library such as @code{libffi}.
1187
1188 The forwarding method implementation thus created is returned by
1189 @code{objc_msg_lookup()} and is executed as if it was a normal method
1190 implementation.  When the forwarding method implementation is called,
1191 it is usually expected to pack all arguments into some sort of object
1192 (typically, an @code{NSInvocation} in a ``Foundation'' library), and
1193 hand it over to the programmer (@code{forwardInvocation:}) who is then
1194 allowed to manipulate the method invocation using a high-level API
1195 provided by the ``Foundation'' library.  For example, the programmer
1196 may want to examine the method invocation arguments and name and
1197 potentially change them before forwarding the method invocation to one
1198 or more local objects (@code{performInvocation:}) or even to remote
1199 objects (by using Distributed Objects or some other mechanism).  When
1200 all this completes, the return value is passed back and must be
1201 returned correctly to the original caller.
1202
1203 Note that the GNU Objective-C runtime currently provides no support
1204 for method forwarding or method invocations other than the
1205 @code{__objc_msg_forward2} hook.
1206
1207 If the forwarding hook does not exist or returns @code{NULL}, the
1208 runtime currently attempts forwarding using an older, deprecated API,
1209 and if that fails, it aborts the program.  In future versions of the
1210 GNU Objective-C runtime, the runtime will immediately abort.