Mercurial > hg > CbC > CbC_gcc
comparison gcc/doc/objc.texi @ 0:a06113de4d67
first commit
author | kent <kent@cr.ie.u-ryukyu.ac.jp> |
---|---|
date | Fri, 17 Jul 2009 14:47:48 +0900 |
parents | |
children | f6334be47118 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:a06113de4d67 |
---|---|
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 |