|
0
|
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.
|
|
|
5
|
|
|
6 @node Objective-C
|
|
|
7 @comment node-name, next, previous, up
|
|
|
8
|
|
|
9 @chapter GNU Objective-C runtime features
|
|
|
10
|
|
|
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}.
|
|
|
16
|
|
|
17 @menu
|
|
|
18 * Executing code before main::
|
|
|
19 * Type encoding::
|
|
|
20 * Garbage Collection::
|
|
|
21 * Constant string objects::
|
|
|
22 * compatibility_alias::
|
|
|
23 @end menu
|
|
|
24
|
|
|
25 @node Executing code before main, Type encoding, Objective-C, Objective-C
|
|
|
26 @section @code{+load}: Executing code before main
|
|
|
27
|
|
|
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}.
|
|
|
32
|
|
|
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.
|
|
|
39
|
|
|
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:
|
|
|
43
|
|
|
44 @smallexample
|
|
|
45
|
|
|
46 FileStream *Stdin = nil;
|
|
|
47 FileStream *Stdout = nil;
|
|
|
48 FileStream *Stderr = nil;
|
|
|
49
|
|
|
50 @@implementation FileStream
|
|
|
51
|
|
|
52 + (void)initialize
|
|
|
53 @{
|
|
|
54 Stdin = [[FileStream new] initWithFd:0];
|
|
|
55 Stdout = [[FileStream new] initWithFd:1];
|
|
|
56 Stderr = [[FileStream new] initWithFd:2];
|
|
|
57 @}
|
|
|
58
|
|
|
59 /* @r{Other methods here} */
|
|
|
60 @@end
|
|
|
61
|
|
|
62 @end smallexample
|
|
|
63
|
|
|
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}.
|
|
|
72
|
|
|
73 The correct solution of the above problem is to use the @code{+load}
|
|
|
74 method instead of @code{+initialize}:
|
|
|
75
|
|
|
76 @smallexample
|
|
|
77
|
|
|
78 @@implementation FileStream
|
|
|
79
|
|
|
80 + (void)load
|
|
|
81 @{
|
|
|
82 Stdin = [[FileStream new] initWithFd:0];
|
|
|
83 Stdout = [[FileStream new] initWithFd:1];
|
|
|
84 Stderr = [[FileStream new] initWithFd:2];
|
|
|
85 @}
|
|
|
86
|
|
|
87 /* @r{Other methods here} */
|
|
|
88 @@end
|
|
|
89
|
|
|
90 @end smallexample
|
|
|
91
|
|
|
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.
|
|
|
96
|
|
|
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}.
|
|
|
100
|
|
|
101 @menu
|
|
|
102 * What you can and what you cannot do in +load::
|
|
|
103 @end menu
|
|
|
104
|
|
|
105
|
|
|
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}
|
|
|
108
|
|
|
109 The @code{+load} implementation in the GNU runtime guarantees you the following
|
|
|
110 things:
|
|
|
111
|
|
|
112 @itemize @bullet
|
|
|
113
|
|
|
114 @item
|
|
|
115 you can write whatever C code you like;
|
|
|
116
|
|
|
117 @item
|
|
|
118 you can send messages to Objective-C constant strings (@code{@@"this is a
|
|
|
119 constant string"});
|
|
|
120
|
|
|
121 @item
|
|
|
122 you can allocate and send messages to objects whose class is implemented
|
|
|
123 in the same file;
|
|
|
124
|
|
|
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;
|
|
|
127
|
|
|
128 @item
|
|
|
129 the @code{+load} implementation of a class is executed before the
|
|
|
130 @code{+load} implementation of any category.
|
|
|
131
|
|
|
132 @end itemize
|
|
|
133
|
|
|
134 In particular, the following things, even if they can work in a
|
|
|
135 particular case, are not guaranteed:
|
|
|
136
|
|
|
137 @itemize @bullet
|
|
|
138
|
|
|
139 @item
|
|
|
140 allocation of or sending messages to arbitrary objects;
|
|
|
141
|
|
|
142 @item
|
|
|
143 allocation of or sending messages to objects whose classes have a
|
|
|
144 category implemented in the same file;
|
|
|
145
|
|
|
146 @end itemize
|
|
|
147
|
|
|
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.
|
|
|
151
|
|
|
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.
|
|
|
160
|
|
|
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.
|
|
|
167
|
|
|
168
|
|
|
169
|
|
|
170 @node Type encoding, Garbage Collection, Executing code before main, Objective-C
|
|
|
171 @section Type encoding
|
|
|
172
|
|
|
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.
|
|
|
176
|
|
|
177 The types are encoded in the following way:
|
|
|
178
|
|
|
179 @c @sp 1
|
|
|
180
|
|
|
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
|
|
|
225
|
|
|
226 @c @sp 1
|
|
|
227
|
|
|
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.
|
|
|
237
|
|
|
238 The position in the bit-field is the position, counting in bits, of the
|
|
|
239 bit closest to the beginning of the structure.
|
|
|
240
|
|
|
241 The non-atomic types are encoded as follows:
|
|
|
242
|
|
|
243 @c @sp 1
|
|
|
244
|
|
|
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
|
|
|
255
|
|
|
256 Here are some types and their encodings, as they are generated by the
|
|
|
257 compiler on an i386 machine:
|
|
|
258
|
|
|
259 @sp 1
|
|
|
260
|
|
|
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;
|
|
|
277 @}
|
|
|
278 @end smallexample
|
|
|
279 @tab @code{@{?=i[3f]b128i3b131i2c@}}
|
|
|
280 @end multitable
|
|
|
281
|
|
|
282 @sp 1
|
|
|
283
|
|
|
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:
|
|
|
287
|
|
|
288 @sp 1
|
|
|
289
|
|
|
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
|
|
|
306
|
|
|
307 @sp 1
|
|
|
308
|
|
|
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.
|
|
|
312
|
|
|
313
|
|
|
314 @node Garbage Collection, Constant string objects, Type encoding, Objective-C
|
|
|
315 @section Garbage Collection
|
|
|
316
|
|
|
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/}}.
|
|
|
321
|
|
|
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.
|
|
|
329
|
|
|
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.
|
|
|
335
|
|
|
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}.
|
|
|
345
|
|
|
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:
|
|
|
349
|
|
|
350 @smallexample
|
|
|
351
|
|
|
352 @@interface WeakPointer : Object
|
|
|
353 @{
|
|
|
354 const void* weakPointer;
|
|
|
355 @}
|
|
|
356
|
|
|
357 - initWithPointer:(const void*)p;
|
|
|
358 - (const void*)weakPointer;
|
|
|
359 @@end
|
|
|
360
|
|
|
361
|
|
|
362 @@implementation WeakPointer
|
|
|
363
|
|
|
364 + (void)initialize
|
|
|
365 @{
|
|
|
366 class_ivar_set_gcinvisible (self, "weakPointer", YES);
|
|
|
367 @}
|
|
|
368
|
|
|
369 - initWithPointer:(const void*)p
|
|
|
370 @{
|
|
|
371 weakPointer = p;
|
|
|
372 return self;
|
|
|
373 @}
|
|
|
374
|
|
|
375 - (const void*)weakPointer
|
|
|
376 @{
|
|
|
377 return weakPointer;
|
|
|
378 @}
|
|
|
379
|
|
|
380 @@end
|
|
|
381
|
|
|
382 @end smallexample
|
|
|
383
|
|
|
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.
|
|
|
389
|
|
|
390 @c =========================================================================
|
|
|
391 @node Constant string objects
|
|
|
392 @section Constant string objects
|
|
|
393
|
|
|
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{@@}:
|
|
|
397
|
|
|
398 @smallexample
|
|
|
399 id myString = @@"this is a constant string object";
|
|
|
400 @end smallexample
|
|
|
401
|
|
|
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.
|
|
|
406
|
|
|
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:
|
|
|
412
|
|
|
413 @smallexample
|
|
|
414
|
|
|
415 @@interface MyConstantStringClass
|
|
|
416 @{
|
|
|
417 Class isa;
|
|
|
418 char *c_string;
|
|
|
419 unsigned int len;
|
|
|
420 @}
|
|
|
421 @@end
|
|
|
422
|
|
|
423 @end smallexample
|
|
|
424
|
|
|
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.
|
|
|
431
|
|
|
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).
|
|
|
443
|
|
|
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.
|
|
|
450
|
|
|
451 @c =========================================================================
|
|
|
452 @node compatibility_alias
|
|
|
453 @section compatibility_alias
|
|
|
454
|
|
|
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.
|
|
|
458
|
|
|
459 The keyword @code{@@compatibility_alias} allows you to define a class name
|
|
|
460 as equivalent to another class name. For example:
|
|
|
461
|
|
|
462 @smallexample
|
|
|
463 @@compatibility_alias WOApplication GSWApplication;
|
|
|
464 @end smallexample
|
|
|
465
|
|
|
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}).
|
|
|
469
|
|
|
470 There are some constraints on how this can be used---
|
|
|
471
|
|
|
472 @itemize @bullet
|
|
|
473
|
|
|
474 @item @code{WOApplication} (the alias) must not be an existing class;
|
|
|
475
|
|
|
476 @item @code{GSWApplication} (the real class) must be an existing class.
|
|
|
477
|
|
|
478 @end itemize
|
