2006-03-15 Paul Brook <paul@codesourcery.com>
[official-gcc.git] / gcc / doc / objc.texi
blobc15c1acf8484418784141c49a4366f382d186697
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.
6 @node Objective-C
7 @comment  node-name,  next,  previous,  up
9 @chapter GNU Objective-C runtime features
11 This document is meant to describe some of the GNU Objective-C runtime
12 features.  It is not intended to teach you Objective-C, there are several
13 resources on the Internet that present the language.  Questions and
14 comments about this document to Ovidiu Predescu
15 @email{ovidiu@@cup.hp.com}.
17 @menu
18 * Executing code before main::
19 * Type encoding::
20 * Garbage Collection::
21 * Constant string objects::
22 * compatibility_alias::
23 @end menu
25 @node Executing code before main, Type encoding, Objective-C, Objective-C
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
42 below:
44 @smallexample
46 FileStream *Stdin = nil;
47 FileStream *Stdout = nil;
48 FileStream *Stderr = nil;
50 @@implementation FileStream
52 + (void)initialize
54     Stdin = [[FileStream new] initWithFd:0];
55     Stdout = [[FileStream new] initWithFd:1];
56     Stderr = [[FileStream new] initWithFd:2];
59 /* @r{Other methods here} */
60 @@end
62 @end smallexample
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}:
76 @smallexample
78 @@implementation FileStream
80 + (void)load
82     Stdin = [[FileStream new] initWithFd:0];
83     Stdout = [[FileStream new] initWithFd:1];
84     Stderr = [[FileStream new] initWithFd:2];
87 /* @r{Other methods here} */
88 @@end
90 @end smallexample
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
95 a category.
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}.
101 @menu
102 * What you can and what you cannot do in +load::
103 @end menu
106 @node What you can and what you cannot do in +load,  , Executing code before main, Executing code before main
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
110 things:
112 @itemize @bullet
114 @item
115 you can write whatever C code you like;
117 @item
118 you can send messages to Objective-C constant strings (@code{@@"this is a
119 constant string"});
121 @item
122 you can allocate and send messages to objects whose class is implemented
123 in the same file;
125 @item
126 the @code{+load} implementation of all super classes of a class are executed before the @code{+load} of that class is executed;
128 @item
129 the @code{+load} implementation of a class is executed before the
130 @code{+load} implementation of any category.
132 @end itemize
134 In particular, the following things, even if they can work in a
135 particular case, are not guaranteed:
137 @itemize @bullet
139 @item
140 allocation of or sending messages to arbitrary objects;
142 @item
143 allocation of or sending messages to objects whose classes have a
144 category implemented in the same file;
146 @end itemize
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.
170 @node Type encoding, Garbage Collection, Executing code before main, Objective-C
171 @section Type encoding
173 The Objective-C compiler generates type encodings for all the
174 types.  These type encodings are used at runtime to find out information
175 about selectors and methods and about objects and classes.
177 The types are encoded in the following way:
179 @c @sp 1
181 @multitable @columnfractions .25 .75
182 @item @code{_Bool}
183 @tab @code{B}
184 @item @code{char}
185 @tab @code{c}
186 @item @code{unsigned char}
187 @tab @code{C}
188 @item @code{short}
189 @tab @code{s}
190 @item @code{unsigned short}
191 @tab @code{S}
192 @item @code{int}
193 @tab @code{i}
194 @item @code{unsigned int}
195 @tab @code{I}
196 @item @code{long}
197 @tab @code{l}
198 @item @code{unsigned long}
199 @tab @code{L}
200 @item @code{long long}
201 @tab @code{q}
202 @item @code{unsigned long long}
203 @tab @code{Q}
204 @item @code{float}
205 @tab @code{f}
206 @item @code{double}
207 @tab @code{d}
208 @item @code{void}
209 @tab @code{v}
210 @item @code{id}
211 @tab @code{@@}
212 @item @code{Class}
213 @tab @code{#}
214 @item @code{SEL}
215 @tab @code{:}
216 @item @code{char*}
217 @tab @code{*}
218 @item unknown type
219 @tab @code{?}
220 @item Complex types
221 @tab @code{j} followed by the inner type.  For example @code{_Complex double} is encoded as "jd".
222 @item bit-fields
223 @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)
224 @end multitable
226 @c @sp 1
228 The encoding of bit-fields has changed to allow bit-fields to be properly
229 handled by the runtime functions that compute sizes and alignments of
230 types that contain bit-fields.  The previous encoding contained only the
231 size of the bit-field.  Using only this information it is not possible to
232 reliably compute the size occupied by the bit-field.  This is very
233 important in the presence of the Boehm's garbage collector because the
234 objects are allocated using the typed memory facility available in this
235 collector.  The typed memory allocation requires information about where
236 the pointers are located inside the object.
238 The position in the bit-field is the position, counting in bits, of the
239 bit closest to the beginning of the structure.
241 The non-atomic types are encoded as follows:
243 @c @sp 1
245 @multitable @columnfractions .2 .8
246 @item pointers
247 @tab @samp{^} followed by the pointed type.
248 @item arrays
249 @tab @samp{[} followed by the number of elements in the array followed by the type of the elements followed by @samp{]}
250 @item structures
251 @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{@}}
252 @item unions
253 @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{)}
254 @end multitable
256 Here are some types and their encodings, as they are generated by the
257 compiler on an i386 machine:
259 @sp 1
261 @multitable @columnfractions .25 .75
262 @item Objective-C type
263 @tab Compiler encoding
264 @item
265 @smallexample
266 int a[10];
267 @end smallexample
268 @tab @code{[10i]}
269 @item
270 @smallexample
271 struct @{
272   int i;
273   float f[3];
274   int a:3;
275   int b:2;
276   char c;
278 @end smallexample
279 @tab @code{@{?=i[3f]b128i3b131i2c@}}
280 @end multitable
282 @sp 1
284 In addition to the types the compiler also encodes the type
285 specifiers.  The table below describes the encoding of the current
286 Objective-C type specifiers:
288 @sp 1
290 @multitable @columnfractions .25 .75
291 @item Specifier
292 @tab Encoding
293 @item @code{const}
294 @tab @code{r}
295 @item @code{in}
296 @tab @code{n}
297 @item @code{inout}
298 @tab @code{N}
299 @item @code{out}
300 @tab @code{o}
301 @item @code{bycopy}
302 @tab @code{O}
303 @item @code{oneway}
304 @tab @code{V}
305 @end multitable
307 @sp 1
309 The type specifiers are encoded just before the type.  Unlike types
310 however, the type specifiers are only encoded when they appear in method
311 argument types.
314 @node Garbage Collection, Constant string objects, Type encoding, Objective-C
315 @section Garbage Collection
317 Support for a new memory management policy has been added by using a
318 powerful conservative garbage collector, known as the
319 Boehm-Demers-Weiser conservative garbage collector.  It is available from
320 @w{@uref{http://www.hpl.hp.com/personal/Hans_Boehm/gc/}}.
322 To enable the support for it you have to configure the compiler using an
323 additional argument, @w{@option{--enable-objc-gc}}.  You need to have
324 garbage collector installed before building the compiler.  This will
325 build an additional runtime library which has several enhancements to
326 support the garbage collector.  The new library has a new name,
327 @file{libobjc_gc.a} to not conflict with the non-garbage-collected
328 library.
330 When the garbage collector is used, the objects are allocated using the
331 so-called typed memory allocation mechanism available in the
332 Boehm-Demers-Weiser collector.  This mode requires precise information on
333 where pointers are located inside objects.  This information is computed
334 once per class, immediately after the class has been initialized.
336 There is a new runtime function @code{class_ivar_set_gcinvisible()}
337 which can be used to declare a so-called @dfn{weak pointer}
338 reference.  Such a pointer is basically hidden for the garbage collector;
339 this can be useful in certain situations, especially when you want to
340 keep track of the allocated objects, yet allow them to be
341 collected.  This kind of pointers can only be members of objects, you
342 cannot declare a global pointer as a weak reference.  Every type which is
343 a pointer type can be declared a weak pointer, including @code{id},
344 @code{Class} and @code{SEL}.
346 Here is an example of how to use this feature.  Suppose you want to
347 implement a class whose instances hold a weak pointer reference; the
348 following class does this:
350 @smallexample
352 @@interface WeakPointer : Object
354     const void* weakPointer;
357 - initWithPointer:(const void*)p;
358 - (const void*)weakPointer;
359 @@end
362 @@implementation WeakPointer
364 + (void)initialize
366   class_ivar_set_gcinvisible (self, "weakPointer", YES);
369 - initWithPointer:(const void*)p
371   weakPointer = p;
372   return self;
375 - (const void*)weakPointer
377   return weakPointer;
380 @@end
382 @end smallexample
384 Weak pointers are supported through a new type character specifier
385 represented by the @samp{!} character.  The
386 @code{class_ivar_set_gcinvisible()} function adds or removes this
387 specifier to the string type description of the instance variable named
388 as argument.
390 @c =========================================================================
391 @node Constant string objects
392 @section Constant string objects
394 GNU Objective-C provides constant string objects that are generated
395 directly by the compiler.  You declare a constant string object by
396 prefixing a C constant string with the character @samp{@@}:
398 @smallexample
399   id myString = @@"this is a constant string object";
400 @end smallexample
402 The constant string objects are by default instances of the
403 @code{NXConstantString} class which is provided by the GNU Objective-C
404 runtime.  To get the definition of this class you must include the
405 @file{objc/NXConstStr.h} header file.
407 User defined libraries may want to implement their own constant string
408 class.  To be able to support them, the GNU Objective-C compiler provides
409 a new command line options @option{-fconstant-string-class=@var{class-name}}.
410 The provided class should adhere to a strict structure, the same
411 as @code{NXConstantString}'s structure:
413 @smallexample
415 @@interface MyConstantStringClass
417   Class isa;
418   char *c_string;
419   unsigned int len;
421 @@end
423 @end smallexample
425 @code{NXConstantString} inherits from @code{Object}; user class
426 libraries may choose to inherit the customized constant string class
427 from a different class than @code{Object}.  There is no requirement in
428 the methods the constant string class has to implement, but the final
429 ivar layout of the class must be the compatible with the given
430 structure.
432 When the compiler creates the statically allocated constant string
433 object, the @code{c_string} field will be filled by the compiler with
434 the string; the @code{length} field will be filled by the compiler with
435 the string length; the @code{isa} pointer will be filled with
436 @code{NULL} by the compiler, and it will later be fixed up automatically
437 at runtime by the GNU Objective-C runtime library to point to the class
438 which was set by the @option{-fconstant-string-class} option when the
439 object file is loaded (if you wonder how it works behind the scenes, the
440 name of the class to use, and the list of static objects to fixup, are
441 stored by the compiler in the object file in a place where the GNU
442 runtime library will find them at runtime).
444 As a result, when a file is compiled with the
445 @option{-fconstant-string-class} option, all the constant string objects
446 will be instances of the class specified as argument to this option.  It
447 is possible to have multiple compilation units referring to different
448 constant string classes, neither the compiler nor the linker impose any
449 restrictions in doing this.
451 @c =========================================================================
452 @node compatibility_alias
453 @section compatibility_alias
455 This is a feature of the Objective-C compiler rather than of the
456 runtime, anyway since it is documented nowhere and its existence was
457 forgotten, we are documenting it here.
459 The keyword @code{@@compatibility_alias} allows you to define a class name
460 as equivalent to another class name.  For example:
462 @smallexample
463 @@compatibility_alias WOApplication GSWApplication;
464 @end smallexample
466 tells the compiler that each time it encounters @code{WOApplication} as
467 a class name, it should replace it with @code{GSWApplication} (that is,
468 @code{WOApplication} is just an alias for @code{GSWApplication}).
470 There are some constraints on how this can be used---
472 @itemize @bullet
474 @item @code{WOApplication} (the alias) must not be an existing class;
476 @item @code{GSWApplication} (the real class) must be an existing class.
478 @end itemize