1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
2 @c 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @comment node-name, next, previous, up
9 @chapter GNU Objective-C features
11 This document is meant to describe some of the GNU Objective-C
12 features. It is not intended to teach you Objective-C, there are
13 several resources on the Internet that present the language.
16 * Executing code before main::
18 * Garbage Collection::
19 * Constant string objects::
20 * compatibility_alias::
25 @node Executing code before main
26 @section @code{+load}: Executing code before main
28 The GNU Objective-C runtime provides a way that allows you to execute
29 code before the execution of the program enters the @code{main}
30 function. The code is executed on a per-class and a per-category basis,
31 through a special class method @code{+load}.
33 This facility is very useful if you want to initialize global variables
34 which can be accessed by the program directly, without sending a message
35 to the class first. The usual way to initialize global variables, in the
36 @code{+initialize} method, might not be useful because
37 @code{+initialize} is only called when the first message is sent to a
38 class object, which in some cases could be too late.
40 Suppose for example you have a @code{FileStream} class that declares
41 @code{Stdin}, @code{Stdout} and @code{Stderr} as global variables, like
46 FileStream *Stdin = nil;
47 FileStream *Stdout = nil;
48 FileStream *Stderr = nil;
50 @@implementation FileStream
54 Stdin = [[FileStream new] initWithFd:0];
55 Stdout = [[FileStream new] initWithFd:1];
56 Stderr = [[FileStream new] initWithFd:2];
59 /* @r{Other methods here} */
64 In this example, the initialization of @code{Stdin}, @code{Stdout} and
65 @code{Stderr} in @code{+initialize} occurs too late. The programmer can
66 send a message to one of these objects before the variables are actually
67 initialized, thus sending messages to the @code{nil} object. The
68 @code{+initialize} method which actually initializes the global
69 variables is not invoked until the first message is sent to the class
70 object. The solution would require these variables to be initialized
71 just before entering @code{main}.
73 The correct solution of the above problem is to use the @code{+load}
74 method instead of @code{+initialize}:
78 @@implementation FileStream
82 Stdin = [[FileStream new] initWithFd:0];
83 Stdout = [[FileStream new] initWithFd:1];
84 Stderr = [[FileStream new] initWithFd:2];
87 /* @r{Other methods here} */
92 The @code{+load} is a method that is not overridden by categories. If a
93 class and a category of it both implement @code{+load}, both methods are
94 invoked. This allows some additional initializations to be performed in
97 This mechanism is not intended to be a replacement for @code{+initialize}.
98 You should be aware of its limitations when you decide to use it
99 instead of @code{+initialize}.
102 * What you can and what you cannot do in +load::
106 @node What you can and what you cannot do in +load
107 @subsection What you can and what you cannot do in @code{+load}
109 The @code{+load} implementation in the GNU runtime guarantees you the following
115 you can write whatever C code you like;
118 you can send messages to Objective-C constant strings (@code{@@"this is a
122 you can allocate and send messages to objects whose class is implemented
126 the @code{+load} implementation of all super classes of a class are executed before the @code{+load} of that class is executed;
129 the @code{+load} implementation of a class is executed before the
130 @code{+load} implementation of any category.
134 In particular, the following things, even if they can work in a
135 particular case, are not guaranteed:
140 allocation of or sending messages to arbitrary objects;
143 allocation of or sending messages to objects whose classes have a
144 category implemented in the same file;
148 You should make no assumptions about receiving @code{+load} in sibling
149 classes when you write @code{+load} of a class. The order in which
150 sibling classes receive @code{+load} is not guaranteed.
152 The order in which @code{+load} and @code{+initialize} are called could
153 be problematic if this matters. If you don't allocate objects inside
154 @code{+load}, it is guaranteed that @code{+load} is called before
155 @code{+initialize}. If you create an object inside @code{+load} the
156 @code{+initialize} method of object's class is invoked even if
157 @code{+load} was not invoked. Note if you explicitly call @code{+load}
158 on a class, @code{+initialize} will be called first. To avoid possible
159 problems try to implement only one of these methods.
161 The @code{+load} method is also invoked when a bundle is dynamically
162 loaded into your running program. This happens automatically without any
163 intervening operation from you. When you write bundles and you need to
164 write @code{+load} you can safely create and send messages to objects whose
165 classes already exist in the running program. The same restrictions as
166 above apply to classes defined in bundle.
171 @section Type encoding
173 This is an advanced section. Type encodings are used extensively by
174 the compiler and by the runtime, but you generally do not need to know
175 about them to use Objective-C.
177 The Objective-C compiler generates type encodings for all the types.
178 These type encodings are used at runtime to find out information about
179 selectors and methods and about objects and classes.
181 The types are encoded in the following way:
185 @multitable @columnfractions .25 .75
190 @item @code{unsigned char}
194 @item @code{unsigned short}
198 @item @code{unsigned int}
202 @item @code{unsigned long}
204 @item @code{long long}
206 @item @code{unsigned long long}
212 @item @code{long double}
225 @tab an @code{enum} is encoded exactly as the integer type that the compiler uses for it, which depends on the enumeration
226 values. Often the compiler users @code{unsigned int}, which is then encoded as @code{I}.
230 @tab @code{j} followed by the inner type. For example @code{_Complex double} is encoded as "jd".
232 @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)
237 The encoding of bit-fields has changed to allow bit-fields to be
238 properly handled by the runtime functions that compute sizes and
239 alignments of types that contain bit-fields. The previous encoding
240 contained only the size of the bit-field. Using only this information
241 it is not possible to reliably compute the size occupied by the
242 bit-field. This is very important in the presence of the Boehm's
243 garbage collector because the objects are allocated using the typed
244 memory facility available in this collector. The typed memory
245 allocation requires information about where the pointers are located
248 The position in the bit-field is the position, counting in bits, of the
249 bit closest to the beginning of the structure.
251 The non-atomic types are encoded as follows:
255 @multitable @columnfractions .2 .8
257 @tab @samp{^} followed by the pointed type.
259 @tab @samp{[} followed by the number of elements in the array followed by the type of the elements followed by @samp{]}
261 @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{@}}
263 @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{)}
265 @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{]}
268 Here are some types and their encodings, as they are generated by the
269 compiler on an i386 machine:
273 @multitable @columnfractions .25 .75
274 @item Objective-C type
275 @tab Compiler encoding
291 @tab @code{@{?=i[3f]b128i3b131i2c@}}
294 int a __attribute__ ((vector_size (16)));
296 @tab @code{![16,16i]} (alignment would depend on the machine)
301 In addition to the types the compiler also encodes the type
302 specifiers. The table below describes the encoding of the current
303 Objective-C type specifiers:
307 @multitable @columnfractions .25 .75
328 The type specifiers are encoded just before the type. Unlike types
329 however, the type specifiers are only encoded when they appear in method
332 Note how @code{const} interacts with pointers:
336 @multitable @columnfractions .25 .75
337 @item Objective-C type
338 @tab Compiler encoding
358 @code{const int*} is a pointer to a @code{const int}, and so is
359 encoded as @code{^ri}. @code{int* const}, instead, is a @code{const}
360 pointer to an @code{int}, and so is encoded as @code{r^i}.
362 Finally, there is a complication when encoding @code{const char *}
363 versus @code{char * const}. Because @code{char *} is encoded as
364 @code{*} and not as @code{^c}, there is no way to express the fact
365 that @code{r} applies to the pointer or to the pointee.
367 Hence, it is assumed as a convention that @code{r*} means @code{const
368 char *} (since it is what is most often meant), and there is no way to
369 encode @code{char *const}. @code{char *const} would simply be encoded
370 as @code{*}, and the @code{const} is lost.
373 * Legacy type encoding::
375 * Method signatures::
378 @node Legacy type encoding
379 @subsection Legacy type encoding
381 Unfortunately, historically GCC used to have a number of bugs in its
382 encoding code. The NeXT runtime expects GCC to emit type encodings in
383 this historical format (compatible with GCC-3.3), so when using the
384 NeXT runtime, GCC will introduce on purpose a number of incorrect
390 the read-only qualifier of the pointee gets emitted before the '^'.
391 The read-only qualifier of the pointer itself gets ignored, unless it
392 is a typedef. Also, the 'r' is only emitted for the outermost type.
395 32-bit longs are encoded as 'l' or 'L', but not always. For typedefs,
396 the compiler uses 'i' or 'I' instead if encoding a struct field or a
400 @code{enum}s are always encoded as 'i' (int) even if they are actually
405 In addition to that, the NeXT runtime uses a different encoding for
406 bitfields. It encodes them as @code{b} followed by the size, without
407 a bit offset or the underlying field type.
412 GNU Objective-C supports the @code{@@encode} syntax that allows you to
413 create a type encoding from a C/Objective-C type. For example,
414 @code{@@encode(int)} is compiled by the compiler into @code{"i"}.
416 @code{@@encode} does not support type qualifiers other than
417 @code{const}. For example, @code{@@encode(const char*)} is valid and
418 is compiled into @code{"r*"}, while @code{@@encode(bycopy char *)} is
419 invalid and will cause a compilation error.
421 @node Method signatures
422 @subsection Method signatures
424 This section documents the encoding of method types, which is rarely
425 needed to use Objective-C. You should skip it at a first reading; the
426 runtime provides functions that will work on methods and can walk
427 through the list of parameters and interpret them for you. These
428 functions are part of the public ``API'' and are the preferred way to
429 interact with method signatures from user code.
431 But if you need to debug a problem with method signatures and need to
432 know how they are implemented (ie, the ``ABI''), read on.
434 Methods have their ``signature'' encoded and made available to the
435 runtime. The ``signature'' encodes all the information required to
436 dynamically build invocations of the method at runtime: return type
439 The ``signature'' is a null-terminated string, composed of the following:
444 The return type, including type qualifiers. For example, a method
445 returning @code{int} would have @code{i} here.
448 The total size (in bytes) required to pass all the parameters. This
449 includes the two hidden parameters (the object @code{self} and the
450 method selector @code{_cmd}).
453 Each argument, with the type encoding, followed by the offset (in
454 bytes) of the argument in the list of parameters.
458 For example, a method with no arguments and returning @code{int} would
459 have the signature @code{i8@@0:4} if the size of a pointer is 4. The
460 signature is interpreted as follows: the @code{i} is the return type
461 (an @code{int}), the @code{8} is the total size of the parameters in
462 bytes (two pointers each of size 4), the @code{@@0} is the first
463 parameter (an object at byte offset @code{0}) and @code{:4} is the
464 second parameter (a @code{SEL} at byte offset @code{4}).
466 You can easily find more examples by running the ``strings'' program
467 on an Objective-C object file compiled by GCC. You'll see a lot of
468 strings that look very much like @code{i8@@0:4}. They are signatures
469 of Objective-C methods.
472 @node Garbage Collection
473 @section Garbage Collection
475 Support for garbage collection with the GNU runtime has been added by
476 using a powerful conservative garbage collector, known as the
477 Boehm-Demers-Weiser conservative garbage collector.
479 To enable the support for it you have to configure the compiler using
480 an additional argument, @w{@option{--enable-objc-gc}}. This will
481 build the boehm-gc library, and build an additional runtime library
482 which has several enhancements to support the garbage collector. The
483 new library has a new name, @file{libobjc_gc.a} to not conflict with
484 the non-garbage-collected library.
486 When the garbage collector is used, the objects are allocated using the
487 so-called typed memory allocation mechanism available in the
488 Boehm-Demers-Weiser collector. This mode requires precise information on
489 where pointers are located inside objects. This information is computed
490 once per class, immediately after the class has been initialized.
492 There is a new runtime function @code{class_ivar_set_gcinvisible()}
493 which can be used to declare a so-called @dfn{weak pointer}
494 reference. Such a pointer is basically hidden for the garbage collector;
495 this can be useful in certain situations, especially when you want to
496 keep track of the allocated objects, yet allow them to be
497 collected. This kind of pointers can only be members of objects, you
498 cannot declare a global pointer as a weak reference. Every type which is
499 a pointer type can be declared a weak pointer, including @code{id},
500 @code{Class} and @code{SEL}.
502 Here is an example of how to use this feature. Suppose you want to
503 implement a class whose instances hold a weak pointer reference; the
504 following class does this:
508 @@interface WeakPointer : Object
510 const void* weakPointer;
513 - initWithPointer:(const void*)p;
514 - (const void*)weakPointer;
518 @@implementation WeakPointer
522 class_ivar_set_gcinvisible (self, "weakPointer", YES);
525 - initWithPointer:(const void*)p
531 - (const void*)weakPointer
540 Weak pointers are supported through a new type character specifier
541 represented by the @samp{!} character. The
542 @code{class_ivar_set_gcinvisible()} function adds or removes this
543 specifier to the string type description of the instance variable named
546 @c =========================================================================
547 @node Constant string objects
548 @section Constant string objects
550 GNU Objective-C provides constant string objects that are generated
551 directly by the compiler. You declare a constant string object by
552 prefixing a C constant string with the character @samp{@@}:
555 id myString = @@"this is a constant string object";
558 The constant string objects are by default instances of the
559 @code{NXConstantString} class which is provided by the GNU Objective-C
560 runtime. To get the definition of this class you must include the
561 @file{objc/NXConstStr.h} header file.
563 User defined libraries may want to implement their own constant string
564 class. To be able to support them, the GNU Objective-C compiler provides
565 a new command line options @option{-fconstant-string-class=@var{class-name}}.
566 The provided class should adhere to a strict structure, the same
567 as @code{NXConstantString}'s structure:
571 @@interface MyConstantStringClass
581 @code{NXConstantString} inherits from @code{Object}; user class
582 libraries may choose to inherit the customized constant string class
583 from a different class than @code{Object}. There is no requirement in
584 the methods the constant string class has to implement, but the final
585 ivar layout of the class must be the compatible with the given
588 When the compiler creates the statically allocated constant string
589 object, the @code{c_string} field will be filled by the compiler with
590 the string; the @code{length} field will be filled by the compiler with
591 the string length; the @code{isa} pointer will be filled with
592 @code{NULL} by the compiler, and it will later be fixed up automatically
593 at runtime by the GNU Objective-C runtime library to point to the class
594 which was set by the @option{-fconstant-string-class} option when the
595 object file is loaded (if you wonder how it works behind the scenes, the
596 name of the class to use, and the list of static objects to fixup, are
597 stored by the compiler in the object file in a place where the GNU
598 runtime library will find them at runtime).
600 As a result, when a file is compiled with the
601 @option{-fconstant-string-class} option, all the constant string objects
602 will be instances of the class specified as argument to this option. It
603 is possible to have multiple compilation units referring to different
604 constant string classes, neither the compiler nor the linker impose any
605 restrictions in doing this.
607 @c =========================================================================
608 @node compatibility_alias
609 @section compatibility_alias
611 The keyword @code{@@compatibility_alias} allows you to define a class name
612 as equivalent to another class name. For example:
615 @@compatibility_alias WOApplication GSWApplication;
618 tells the compiler that each time it encounters @code{WOApplication} as
619 a class name, it should replace it with @code{GSWApplication} (that is,
620 @code{WOApplication} is just an alias for @code{GSWApplication}).
622 There are some constraints on how this can be used---
626 @item @code{WOApplication} (the alias) must not be an existing class;
628 @item @code{GSWApplication} (the real class) must be an existing class.
632 @c =========================================================================
636 GNU Objective-C provides exception support built into the language, as
637 in the following example:
645 @@catch (AnObjCClass *exc) @{
652 @@catch (AnotherClass *exc) @{
655 @@catch (id allOthers) @{
665 The @code{@@throw} statement may appear anywhere in an Objective-C or
666 Objective-C++ program; when used inside of a @code{@@catch} block, the
667 @code{@@throw} may appear without an argument (as shown above), in
668 which case the object caught by the @code{@@catch} will be rethrown.
670 Note that only (pointers to) Objective-C objects may be thrown and
671 caught using this scheme. When an object is thrown, it will be caught
672 by the nearest @code{@@catch} clause capable of handling objects of
673 that type, analogously to how @code{catch} blocks work in C++ and
674 Java. A @code{@@catch(id @dots{})} clause (as shown above) may also
675 be provided to catch any and all Objective-C exceptions not caught by
676 previous @code{@@catch} clauses (if any).
678 The @code{@@finally} clause, if present, will be executed upon exit
679 from the immediately preceding @code{@@try @dots{} @@catch} section.
680 This will happen regardless of whether any exceptions are thrown,
681 caught or rethrown inside the @code{@@try @dots{} @@catch} section,
682 analogously to the behavior of the @code{finally} clause in Java.
684 There are several caveats to using the new exception mechanism:
688 The @option{-fobjc-exceptions} command line option must be used when
689 compiling Objective-C files that use exceptions.
692 With the GNU runtime, exceptions are always implemented as ``native''
693 exceptions and it is recommended that the @option{-fexceptions} and
694 @option{-shared-libgcc} options are used when linking.
697 With the NeXT runtime, although currently designed to be binary
698 compatible with @code{NS_HANDLER}-style idioms provided by the
699 @code{NSException} class, the new exceptions can only be used on Mac
700 OS X 10.3 (Panther) and later systems, due to additional functionality
701 needed in the NeXT Objective-C runtime.
704 As mentioned above, the new exceptions do not support handling
705 types other than Objective-C objects. Furthermore, when used from
706 Objective-C++, the Objective-C exception model does not interoperate with C++
707 exceptions at this time. This means you cannot @code{@@throw} an exception
708 from Objective-C and @code{catch} it in C++, or vice versa
709 (i.e., @code{throw @dots{} @@catch}).
712 @c =========================================================================
713 @node Synchronization
714 @section Synchronization
716 GNU Objective-C provides support for synchronized blocks:
719 @@synchronized (ObjCClass *guard) @{
724 Upon entering the @code{@@synchronized} block, a thread of execution
725 shall first check whether a lock has been placed on the corresponding
726 @code{guard} object by another thread. If it has, the current thread
727 shall wait until the other thread relinquishes its lock. Once
728 @code{guard} becomes available, the current thread will place its own
729 lock on it, execute the code contained in the @code{@@synchronized}
730 block, and finally relinquish the lock (thereby making @code{guard}
731 available to other threads).
733 Unlike Java, Objective-C does not allow for entire methods to be
734 marked @code{@@synchronized}. Note that throwing exceptions out of
735 @code{@@synchronized} blocks is allowed, and will cause the guarding
736 object to be unlocked properly.
738 Because of the interactions between synchronization and exception
739 handling, you can only use @code{@@synchronized} when compiling with
740 exceptions enabled, that is with the command line option
741 @option{-fobjc-exceptions}.