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