]>
Commit | Line | Data |
---|---|---|
f1717362 | 1 | @c Copyright (C) 1988-2016 Free Software Foundation, Inc. |
6b515411 | 2 | @c This is part of the GCC manual. |
3 | @c For copying conditions, see the file gcc.texi. | |
4 | ||
3db5236b | 5 | @node Objective-C |
13cc7b4d | 6 | @comment node-name, next, previous, up |
7 | ||
7760911e | 8 | @chapter GNU Objective-C Features |
d41977e4 | 9 | |
34e11ec7 | 10 | This document is meant to describe some of the GNU Objective-C |
116d575b | 11 | features. It is not intended to teach you Objective-C. There are |
34e11ec7 | 12 | several resources on the Internet that present the language. |
d41977e4 | 13 | |
8692c712 | 14 | @menu |
116d575b | 15 | * GNU Objective-C runtime API:: |
77f71523 | 16 | * Executing code before main:: |
17 | * Type encoding:: | |
18 | * Garbage Collection:: | |
19 | * Constant string objects:: | |
dcd9df6c | 20 | * compatibility_alias:: |
34e11ec7 | 21 | * Exceptions:: |
22 | * Synchronization:: | |
0a65c3bb | 23 | * Fast enumeration:: |
9cabc8a4 | 24 | * Messaging with the GNU Objective-C runtime:: |
8692c712 | 25 | @end menu |
d41977e4 | 26 | |
116d575b | 27 | @c ========================================================================= |
28 | @node GNU Objective-C runtime API | |
7760911e | 29 | @section GNU Objective-C Runtime API |
116d575b | 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 | |
7760911e | 53 | @subsection Modern GNU Objective-C Runtime API |
116d575b | 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 | ||
9cabc8a4 | 107 | The header files contain detailed documentation for each function in |
108 | the GNU Objective-C runtime API. | |
109 | ||
116d575b | 110 | @c ========================================================================= |
111 | @node Traditional GNU Objective-C runtime API | |
7760911e | 112 | @subsection Traditional GNU Objective-C Runtime API |
116d575b | 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 | ||
ba3f7241 | 122 | Starting with GCC 4.7.0, the traditional GNU runtime API is no longer |
123 | available. | |
116d575b | 124 | |
125 | @c ========================================================================= | |
34e11ec7 | 126 | @node Executing code before main |
7760911e | 127 | @section @code{+load}: Executing Code before @code{main} |
d41977e4 | 128 | |
116d575b | 129 | This section is specific for the GNU Objective-C runtime. If you are |
130 | using a different runtime, you can skip it. | |
131 | ||
d41977e4 | 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} | |
71d6ad5e | 134 | function. The code is executed on a per-class and a per-category basis, |
d41977e4 | 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 | |
71d6ad5e | 139 | to the class first. The usual way to initialize global variables, in the |
d41977e4 | 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 | ||
a0ecd6b1 | 148 | @smallexample |
77f71523 | 149 | |
150 | FileStream *Stdin = nil; | |
151 | FileStream *Stdout = nil; | |
152 | FileStream *Stderr = nil; | |
153 | ||
154 | @@implementation FileStream | |
155 | ||
156 | + (void)initialize | |
d41977e4 | 157 | @{ |
77f71523 | 158 | Stdin = [[FileStream new] initWithFd:0]; |
159 | Stdout = [[FileStream new] initWithFd:1]; | |
d41977e4 | 160 | Stderr = [[FileStream new] initWithFd:2]; |
161 | @} | |
77f71523 | 162 | |
12e2a142 | 163 | /* @r{Other methods here} */ |
d41977e4 | 164 | @@end |
165 | ||
a0ecd6b1 | 166 | @end smallexample |
d41977e4 | 167 | |
168 | In this example, the initialization of @code{Stdin}, @code{Stdout} and | |
71d6ad5e | 169 | @code{Stderr} in @code{+initialize} occurs too late. The programmer can |
d41977e4 | 170 | send a message to one of these objects before the variables are actually |
71d6ad5e | 171 | initialized, thus sending messages to the @code{nil} object. The |
d41977e4 | 172 | @code{+initialize} method which actually initializes the global |
173 | variables is not invoked until the first message is sent to the class | |
71d6ad5e | 174 | object. The solution would require these variables to be initialized |
d41977e4 | 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 | ||
a0ecd6b1 | 180 | @smallexample |
d41977e4 | 181 | |
77f71523 | 182 | @@implementation FileStream |
183 | ||
184 | + (void)load | |
d41977e4 | 185 | @{ |
186 | Stdin = [[FileStream new] initWithFd:0]; | |
187 | Stdout = [[FileStream new] initWithFd:1]; | |
188 | Stderr = [[FileStream new] initWithFd:2]; | |
189 | @} | |
77f71523 | 190 | |
12e2a142 | 191 | /* @r{Other methods here} */ |
d41977e4 | 192 | @@end |
193 | ||
a0ecd6b1 | 194 | @end smallexample |
77f71523 | 195 | |
71d6ad5e | 196 | The @code{+load} is a method that is not overridden by categories. If a |
d41977e4 | 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. | |
77f71523 | 200 | |
d41977e4 | 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 | |
77f71523 | 206 | * What you can and what you cannot do in +load:: |
d41977e4 | 207 | @end menu |
208 | ||
209 | ||
34e11ec7 | 210 | @node What you can and what you cannot do in +load |
7760911e | 211 | @subsection What You Can and Cannot Do in @code{+load} |
d41977e4 | 212 | |
8e03fb20 | 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: | |
d41977e4 | 221 | |
222 | @itemize @bullet | |
223 | ||
224 | @item | |
225 | you can write whatever C code you like; | |
226 | ||
d41977e4 | 227 | @item |
228 | you can allocate and send messages to objects whose class is implemented | |
229 | in the same file; | |
230 | ||
231 | @item | |
8e03fb20 | 232 | the @code{+load} implementation of all super classes of a class are |
233 | executed before the @code{+load} of that class is executed; | |
d41977e4 | 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 | ||
8e03fb20 | 253 | @item |
254 | sending messages to Objective-C constant strings (@code{@@"this is a | |
255 | constant string"}); | |
256 | ||
d41977e4 | 257 | @end itemize |
258 | ||
259 | You should make no assumptions about receiving @code{+load} in sibling | |
71d6ad5e | 260 | classes when you write @code{+load} of a class. The order in which |
d41977e4 | 261 | sibling classes receive @code{+load} is not guaranteed. |
77f71523 | 262 | |
d41977e4 | 263 | The order in which @code{+load} and @code{+initialize} are called could |
71d6ad5e | 264 | be problematic if this matters. If you don't allocate objects inside |
d41977e4 | 265 | @code{+load}, it is guaranteed that @code{+load} is called before |
71d6ad5e | 266 | @code{+initialize}. If you create an object inside @code{+load} the |
d41977e4 | 267 | @code{+initialize} method of object's class is invoked even if |
71d6ad5e | 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 | |
d41977e4 | 270 | problems try to implement only one of these methods. |
271 | ||
272 | The @code{+load} method is also invoked when a bundle is dynamically | |
71d6ad5e | 273 | loaded into your running program. This happens automatically without any |
274 | intervening operation from you. When you write bundles and you need to | |
d41977e4 | 275 | write @code{+load} you can safely create and send messages to objects whose |
71d6ad5e | 276 | classes already exist in the running program. The same restrictions as |
d41977e4 | 277 | above apply to classes defined in bundle. |
278 | ||
279 | ||
280 | ||
34e11ec7 | 281 | @node Type encoding |
7760911e | 282 | @section Type Encoding |
d41977e4 | 283 | |
f8ee0563 | 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. | |
d41977e4 | 291 | |
292 | The types are encoded in the following way: | |
293 | ||
294 | @c @sp 1 | |
295 | ||
296 | @multitable @columnfractions .25 .75 | |
a4d78591 | 297 | @item @code{_Bool} |
298 | @tab @code{B} | |
77f71523 | 299 | @item @code{char} |
d41977e4 | 300 | @tab @code{c} |
77f71523 | 301 | @item @code{unsigned char} |
d41977e4 | 302 | @tab @code{C} |
77f71523 | 303 | @item @code{short} |
d41977e4 | 304 | @tab @code{s} |
77f71523 | 305 | @item @code{unsigned short} |
d41977e4 | 306 | @tab @code{S} |
77f71523 | 307 | @item @code{int} |
d41977e4 | 308 | @tab @code{i} |
77f71523 | 309 | @item @code{unsigned int} |
d41977e4 | 310 | @tab @code{I} |
77f71523 | 311 | @item @code{long} |
d41977e4 | 312 | @tab @code{l} |
77f71523 | 313 | @item @code{unsigned long} |
d41977e4 | 314 | @tab @code{L} |
77f71523 | 315 | @item @code{long long} |
d41977e4 | 316 | @tab @code{q} |
77f71523 | 317 | @item @code{unsigned long long} |
d41977e4 | 318 | @tab @code{Q} |
77f71523 | 319 | @item @code{float} |
d41977e4 | 320 | @tab @code{f} |
77f71523 | 321 | @item @code{double} |
d41977e4 | 322 | @tab @code{d} |
f8ee0563 | 323 | @item @code{long double} |
324 | @tab @code{D} | |
77f71523 | 325 | @item @code{void} |
d41977e4 | 326 | @tab @code{v} |
77f71523 | 327 | @item @code{id} |
d41977e4 | 328 | @tab @code{@@} |
77f71523 | 329 | @item @code{Class} |
d41977e4 | 330 | @tab @code{#} |
77f71523 | 331 | @item @code{SEL} |
d41977e4 | 332 | @tab @code{:} |
77f71523 | 333 | @item @code{char*} |
d41977e4 | 334 | @tab @code{*} |
f8ee0563 | 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}. | |
77f71523 | 338 | @item unknown type |
d41977e4 | 339 | @tab @code{?} |
a4d78591 | 340 | @item Complex types |
89ec5e21 | 341 | @tab @code{j} followed by the inner type. For example @code{_Complex double} is encoded as "jd". |
8e5fcce7 | 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) | |
d41977e4 | 344 | @end multitable |
345 | ||
346 | @c @sp 1 | |
347 | ||
f8ee0563 | 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. | |
d41977e4 | 358 | |
8e5fcce7 | 359 | The position in the bit-field is the position, counting in bits, of the |
d41977e4 | 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 | |
77f71523 | 367 | @item pointers |
e5e1c255 | 368 | @tab @samp{^} followed by the pointed type. |
d41977e4 | 369 | @item arrays |
e5e1c255 | 370 | @tab @samp{[} followed by the number of elements in the array followed by the type of the elements followed by @samp{]} |
d41977e4 | 371 | @item structures |
e5e1c255 | 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{@}} |
d41977e4 | 373 | @item unions |
e5e1c255 | 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{)} |
f8ee0563 | 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{]} | |
d41977e4 | 377 | @end multitable |
378 | ||
379 | Here are some types and their encodings, as they are generated by the | |
20dd417a | 380 | compiler on an i386 machine: |
d41977e4 | 381 | |
382 | @sp 1 | |
383 | ||
384 | @multitable @columnfractions .25 .75 | |
385 | @item Objective-C type | |
386 | @tab Compiler encoding | |
387 | @item | |
a0ecd6b1 | 388 | @smallexample |
d41977e4 | 389 | int a[10]; |
a0ecd6b1 | 390 | @end smallexample |
d41977e4 | 391 | @tab @code{[10i]} |
392 | @item | |
a0ecd6b1 | 393 | @smallexample |
d41977e4 | 394 | struct @{ |
395 | int i; | |
396 | float f[3]; | |
397 | int a:3; | |
398 | int b:2; | |
399 | char c; | |
400 | @} | |
a0ecd6b1 | 401 | @end smallexample |
d41977e4 | 402 | @tab @code{@{?=i[3f]b128i3b131i2c@}} |
f8ee0563 | 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) | |
d41977e4 | 408 | @end multitable |
409 | ||
410 | @sp 1 | |
411 | ||
412 | In addition to the types the compiler also encodes the type | |
71d6ad5e | 413 | specifiers. The table below describes the encoding of the current |
d41977e4 | 414 | Objective-C type specifiers: |
415 | ||
416 | @sp 1 | |
417 | ||
418 | @multitable @columnfractions .25 .75 | |
419 | @item Specifier | |
420 | @tab Encoding | |
77f71523 | 421 | @item @code{const} |
d41977e4 | 422 | @tab @code{r} |
77f71523 | 423 | @item @code{in} |
d41977e4 | 424 | @tab @code{n} |
77f71523 | 425 | @item @code{inout} |
d41977e4 | 426 | @tab @code{N} |
77f71523 | 427 | @item @code{out} |
d41977e4 | 428 | @tab @code{o} |
77f71523 | 429 | @item @code{bycopy} |
d41977e4 | 430 | @tab @code{O} |
f8ee0563 | 431 | @item @code{byref} |
432 | @tab @code{R} | |
77f71523 | 433 | @item @code{oneway} |
d41977e4 | 434 | @tab @code{V} |
435 | @end multitable | |
436 | ||
437 | @sp 1 | |
438 | ||
71d6ad5e | 439 | The type specifiers are encoded just before the type. Unlike types |
d41977e4 | 440 | however, the type specifiers are only encoded when they appear in method |
441 | argument types. | |
442 | ||
f8ee0563 | 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 | |
7760911e | 490 | @subsection Legacy Type Encoding |
f8ee0563 | 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 | |
7760911e | 521 | @subsection @code{@@encode} |
f8ee0563 | 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 | |
7760911e | 533 | @subsection Method Signatures |
f8ee0563 | 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 | |
b59688ee | 543 | know how they are implemented (i.e., the ``ABI''), read on. |
f8ee0563 | 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 | ||
d41977e4 | 582 | |
34e11ec7 | 583 | @node Garbage Collection |
d41977e4 | 584 | @section Garbage Collection |
585 | ||
116d575b | 586 | This section is specific for the GNU Objective-C runtime. If you are |
587 | using a different runtime, you can skip it. | |
588 | ||
34e11ec7 | 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. | |
d41977e4 | 592 | |
34e11ec7 | 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. | |
d41977e4 | 599 | |
600 | When the garbage collector is used, the objects are allocated using the | |
601 | so-called typed memory allocation mechanism available in the | |
71d6ad5e | 602 | Boehm-Demers-Weiser collector. This mode requires precise information on |
603 | where pointers are located inside objects. This information is computed | |
d41977e4 | 604 | once per class, immediately after the class has been initialized. |
605 | ||
606 | There is a new runtime function @code{class_ivar_set_gcinvisible()} | |
e5e1c255 | 607 | which can be used to declare a so-called @dfn{weak pointer} |
71d6ad5e | 608 | reference. Such a pointer is basically hidden for the garbage collector; |
d41977e4 | 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 | |
71d6ad5e | 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 | |
d41977e4 | 613 | a pointer type can be declared a weak pointer, including @code{id}, |
614 | @code{Class} and @code{SEL}. | |
615 | ||
71d6ad5e | 616 | Here is an example of how to use this feature. Suppose you want to |
d41977e4 | 617 | implement a class whose instances hold a weak pointer reference; the |
618 | following class does this: | |
619 | ||
a0ecd6b1 | 620 | @smallexample |
d41977e4 | 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 | @{ | |
4b8d9456 | 636 | if (self == objc_lookUpClass ("WeakPointer")) |
637 | class_ivar_set_gcinvisible (self, "weakPointer", YES); | |
d41977e4 | 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 | ||
a0ecd6b1 | 653 | @end smallexample |
d41977e4 | 654 | |
655 | Weak pointers are supported through a new type character specifier | |
71d6ad5e | 656 | represented by the @samp{!} character. The |
d41977e4 | 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 | ||
3ec9b0b1 | 661 | @c ========================================================================= |
fa3ae5be | 662 | @node Constant string objects |
7760911e | 663 | @section Constant String Objects |
3ec9b0b1 | 664 | |
665 | GNU Objective-C provides constant string objects that are generated | |
71d6ad5e | 666 | directly by the compiler. You declare a constant string object by |
e5e1c255 | 667 | prefixing a C constant string with the character @samp{@@}: |
3ec9b0b1 | 668 | |
a0ecd6b1 | 669 | @smallexample |
3ec9b0b1 | 670 | id myString = @@"this is a constant string object"; |
a0ecd6b1 | 671 | @end smallexample |
3ec9b0b1 | 672 | |
509cb6a8 | 673 | The constant string objects are by default instances of the |
3ec9b0b1 | 674 | @code{NXConstantString} class which is provided by the GNU Objective-C |
71d6ad5e | 675 | runtime. To get the definition of this class you must include the |
3ec9b0b1 | 676 | @file{objc/NXConstStr.h} header file. |
677 | ||
678 | User defined libraries may want to implement their own constant string | |
71d6ad5e | 679 | class. To be able to support them, the GNU Objective-C compiler provides |
e5e1c255 | 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 | |
3ec9b0b1 | 682 | as @code{NXConstantString}'s structure: |
683 | ||
a0ecd6b1 | 684 | @smallexample |
3ec9b0b1 | 685 | |
509cb6a8 | 686 | @@interface MyConstantStringClass |
3ec9b0b1 | 687 | @{ |
509cb6a8 | 688 | Class isa; |
3ec9b0b1 | 689 | char *c_string; |
690 | unsigned int len; | |
691 | @} | |
692 | @@end | |
693 | ||
a0ecd6b1 | 694 | @end smallexample |
3ec9b0b1 | 695 | |
509cb6a8 | 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 | |
a3af0c0e | 700 | ivar layout of the class must be the compatible with the given |
509cb6a8 | 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. | |
d41977e4 | 721 | |
dcd9df6c | 722 | @c ========================================================================= |
fa3ae5be | 723 | @node compatibility_alias |
7760911e | 724 | @section @code{compatibility_alias} |
dcd9df6c | 725 | |
77f71523 | 726 | The keyword @code{@@compatibility_alias} allows you to define a class name |
727 | as equivalent to another class name. For example: | |
dcd9df6c | 728 | |
a0ecd6b1 | 729 | @smallexample |
dcd9df6c | 730 | @@compatibility_alias WOApplication GSWApplication; |
a0ecd6b1 | 731 | @end smallexample |
d41977e4 | 732 | |
77f71523 | 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, | |
dcd9df6c | 735 | @code{WOApplication} is just an alias for @code{GSWApplication}). |
736 | ||
e5e1c255 | 737 | There are some constraints on how this can be used--- |
dcd9df6c | 738 | |
77f71523 | 739 | @itemize @bullet |
dcd9df6c | 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 | |
34e11ec7 | 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}. | |
0a65c3bb | 857 | |
858 | ||
859 | @c ========================================================================= | |
860 | @node Fast enumeration | |
7760911e | 861 | @section Fast Enumeration |
0a65c3bb | 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 | |
7760911e | 872 | @subsection Using Fast Enumeration |
0a65c3bb | 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 | |
7760911e | 912 | @subsection C99-Like Fast Enumeration Syntax |
0a65c3bb | 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 | |
7760911e | 946 | @subsection Fast Enumeration Details |
0a65c3bb | 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 | |
7760911e | 1009 | @subsection Fast Enumeration Protocol |
0a65c3bb | 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 | |
15b474a2 | 1015 | - (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state |
0a65c3bb | 1016 | objects: (id *)objects |
b59688ee | 1017 | count: (unsigned long)len; |
0a65c3bb | 1018 | @end smallexample |
1019 | ||
1020 | where @code{NSFastEnumerationState} must be defined in your code as follows: | |
1021 | ||
1022 | @smallexample | |
b59688ee | 1023 | typedef struct |
0a65c3bb | 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. | |
31a38208 | 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 | ||
9cabc8a4 | 1077 | @c ========================================================================= |
1078 | @node Messaging with the GNU Objective-C runtime | |
7760911e | 1079 | @section Messaging with the GNU Objective-C Runtime |
9cabc8a4 | 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 | |
7760911e | 1110 | @subsection Dynamically Registering Methods |
9cabc8a4 | 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 | ||
15b474a2 | 1124 | in the case of an instance method, or |
9cabc8a4 | 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 | |
7760911e | 1156 | @subsection Forwarding Hook |
9cabc8a4 | 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 | |
2b139ca6 | 1166 | @code{__objc_msg_forward2} to a function with the same argument and |
9cabc8a4 | 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. |