gcc/objc.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
   2 @c 1999, 2000, 2001 Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node Objective C
   7 @comment  node-name,  next,  previous,  up
   8
   9 @chapter GNU Objective-C runtime features
  10
  11 This document is meant to describe some of the GNU Objective-C runtime
  12 features. It is not intended to teach you Objective-C, there are several
  13 resources on the Internet that present the language.  Questions and
  14 comments about this document to Ovidiu Predescu
  15 @email{ovidiu@@cup.hp.com}.
  16
  17 @menu
  18 * Executing code before main::
  19 * Type encoding::
  20 * Garbage Collection::
  21 * Constant string objects::
  22 @end menu
  23
  24 @node Executing code before main, Type encoding, Objective C, Objective C
  25 @section @code{+load}: Executing code before main
  26
  27
  28 The GNU Objective-C runtime provides a way that allows you to execute
  29 code before the execution of the program enters the @code{main}
  30 function. The code is executed on a per-class and a per-category basis,
  31 through a special class method @code{+load}.
  32
  33 This facility is very useful if you want to initialize global variables
  34 which can be accessed by the program directly, without sending a message
  35 to the class first. The usual way to initialize global variables, in the
  36 @code{+initialize} method, might not be useful because
  37 @code{+initialize} is only called when the first message is sent to a
  38 class object, which in some cases could be too late.
  39
  40 Suppose for example you have a @code{FileStream} class that declares
  41 @code{Stdin}, @code{Stdout} and @code{Stderr} as global variables, like
  42 below:
  43
  44 @example
  45
  46 FileStream *Stdin = nil;
  47 FileStream *Stdout = nil;
  48 FileStream *Stderr = nil;
  49
  50 @@implementation FileStream
  51
  52 + (void)initialize
  53 @{
  54     Stdin = [[FileStream new] initWithFd:0];
  55     Stdout = [[FileStream new] initWithFd:1];
  56     Stderr = [[FileStream new] initWithFd:2];
  57 @}
  58
  59 /* Other methods here */
  60 @@end
  61
  62 @end example
  63
  64 In this example, the initialization of @code{Stdin}, @code{Stdout} and
  65 @code{Stderr} in @code{+initialize} occurs too late. The programmer can
  66 send a message to one of these objects before the variables are actually
  67 initialized, thus sending messages to the @code{nil} object. The
  68 @code{+initialize} method which actually initializes the global
  69 variables is not invoked until the first message is sent to the class
  70 object. The solution would require these variables to be initialized
  71 just before entering @code{main}.
  72
  73 The correct solution of the above problem is to use the @code{+load}
  74 method instead of @code{+initialize}:
  75
  76 @example
  77
  78 @@implementation FileStream
  79
  80 + (void)load
  81 @{
  82     Stdin = [[FileStream new] initWithFd:0];
  83     Stdout = [[FileStream new] initWithFd:1];
  84     Stderr = [[FileStream new] initWithFd:2];
  85 @}
  86
  87 /* Other methods here */
  88 @@end
  89
  90 @end example
  91
  92 The @code{+load} is a method that is not overridden by categories. If a
  93 class and a category of it both implement @code{+load}, both methods are
  94 invoked.  This allows some additional initializations to be performed in
  95 a category.
  96
  97 This mechanism is not intended to be a replacement for @code{+initialize}.
  98 You should be aware of its limitations when you decide to use it
  99 instead of @code{+initialize}.
 100
 101 @menu
 102 * What you can and what you cannot do in +load::
 103 @end menu
 104
 105
 106 @node What you can and what you cannot do in +load,  , Executing code before main, Executing code before main
 107 @subsection What you can and what you cannot do in @code{+load}
 108
 109 The @code{+load} implementation in the GNU runtime guarantees you the following
 110 things:
 111
 112 @itemize @bullet
 113
 114 @item
 115 you can write whatever C code you like;
 116
 117 @item
 118 you can send messages to Objective-C constant strings (@@"this is a
 119 constant string");
 120
 121 @item
 122 you can allocate and send messages to objects whose class is implemented
 123 in the same file;
 124
 125 @item
 126 the @code{+load} implementation of all super classes of a class are executed before the @code{+load} of that class is executed;
 127
 128 @item
 129 the @code{+load} implementation of a class is executed before the
 130 @code{+load} implementation of any category.
 131
 132 @end itemize
 133
 134 In particular, the following things, even if they can work in a
 135 particular case, are not guaranteed:
 136
 137 @itemize @bullet
 138
 139 @item
 140 allocation of or sending messages to arbitrary objects;
 141
 142 @item
 143 allocation of or sending messages to objects whose classes have a
 144 category implemented in the same file;
 145
 146 @end itemize
 147
 148 You should make no assumptions about receiving @code{+load} in sibling
 149 classes when you write @code{+load} of a class. The order in which
 150 sibling classes receive @code{+load} is not guaranteed.
 151
 152 The order in which @code{+load} and @code{+initialize} are called could
 153 be problematic if this matters. If you don't allocate objects inside
 154 @code{+load}, it is guaranteed that @code{+load} is called before
 155 @code{+initialize}. If you create an object inside @code{+load} the
 156 @code{+initialize} method of object's class is invoked even if
 157 @code{+load} was not invoked. Note if you explicitly call @code{+load}
 158 on a class, @code{+initialize} will be called first. To avoid possible
 159 problems try to implement only one of these methods.
 160
 161 The @code{+load} method is also invoked when a bundle is dynamically
 162 loaded into your running program. This happens automatically without any
 163 intervening operation from you. When you write bundles and you need to
 164 write @code{+load} you can safely create and send messages to objects whose
 165 classes already exist in the running program. The same restrictions as
 166 above apply to classes defined in bundle.
 167
 168
 169
 170 @node Type encoding, Garbage Collection, Executing code before main, Objective C
 171 @section Type encoding
 172
 173 The Objective-C compiler generates type encodings for all the
 174 types. These type encodings are used at runtime to find out information
 175 about selectors and methods and about objects and classes.
 176
 177 The types are encoded in the following way:
 178
 179 @c @sp 1
 180
 181 @multitable @columnfractions .25 .75
 182 @item @code{char}
 183 @tab @code{c}
 184 @item @code{unsigned char}
 185 @tab @code{C}
 186 @item @code{short}
 187 @tab @code{s}
 188 @item @code{unsigned short}
 189 @tab @code{S}
 190 @item @code{int}
 191 @tab @code{i}
 192 @item @code{unsigned int}
 193 @tab @code{I}
 194 @item @code{long}
 195 @tab @code{l}
 196 @item @code{unsigned long}
 197 @tab @code{L}
 198 @item @code{long long}
 199 @tab @code{q}
 200 @item @code{unsigned long long}
 201 @tab @code{Q}
 202 @item @code{float}
 203 @tab @code{f}
 204 @item @code{double}
 205 @tab @code{d}
 206 @item @code{void}
 207 @tab @code{v}
 208 @item @code{id}
 209 @tab @code{@@}
 210 @item @code{Class}
 211 @tab @code{#}
 212 @item @code{SEL}
 213 @tab @code{:}
 214 @item @code{char*}
 215 @tab @code{*}
 216 @item unknown type
 217 @tab @code{?}
 218 @item bitfields
 219 @tab @code{b} followed by the starting position of the bitfield, the type of the bitfield and the size of the bitfield (the bitfields encoding was changed from the NeXT's compiler encoding, see below)
 220 @end multitable
 221
 222 @c @sp 1
 223
 224 The encoding of bitfields has changed to allow bitfields to be properly
 225 handled by the runtime functions that compute sizes and alignments of
 226 types that contain bitfields. The previous encoding contained only the
 227 size of the bitfield. Using only this information it is not possible to
 228 reliably compute the size occupied by the bitfield. This is very
 229 important in the presence of the Boehm's garbage collector because the
 230 objects are allocated using the typed memory facility available in this
 231 collector. The typed memory allocation requires information about where
 232 the pointers are located inside the object.
 233
 234 The position in the bitfield is the position, counting in bits, of the
 235 bit closest to the beginning of the structure.
 236
 237 The non-atomic types are encoded as follows:
 238
 239 @c @sp 1
 240
 241 @multitable @columnfractions .2 .8
 242 @item pointers
 243 @tab @code{'^'} followed by the pointed type.
 244 @item arrays
 245 @tab @code{'['} followed by the number of elements in the array followed by the type of the elements followed by @code{']'}
 246 @item structures
 247 @tab @code{'@{'} followed by the name of the structure (or '?' if the structure is unnamed), the '=' sign, the type of the members and by @code{'@}'}
 248 @item unions
 249 @tab @code{'('} followed by the name of the structure (or '?' if the union is unnamed), the '=' sign, the type of the members followed by @code{')'}
 250 @end multitable
 251
 252 Here are some types and their encodings, as they are generated by the
 253 compiler on a i386 machine:
 254
 255 @sp 1
 256
 257 @multitable @columnfractions .25 .75
 258 @item Objective-C type
 259 @tab Compiler encoding
 260 @item
 261 @example
 262 int a[10];
 263 @end example
 264 @tab @code{[10i]}
 265 @item
 266 @example
 267 struct @{
 268   int i;
 269   float f[3];
 270   int a:3;
 271   int b:2;
 272   char c;
 273 @}
 274 @end example
 275 @tab @code{@{?=i[3f]b128i3b131i2c@}}
 276 @end multitable
 277
 278 @sp 1
 279
 280 In addition to the types the compiler also encodes the type
 281 specifiers. The table below describes the encoding of the current
 282 Objective-C type specifiers:
 283
 284 @sp 1
 285
 286 @multitable @columnfractions .25 .75
 287 @item Specifier
 288 @tab Encoding
 289 @item @code{const}
 290 @tab @code{r}
 291 @item @code{in}
 292 @tab @code{n}
 293 @item @code{inout}
 294 @tab @code{N}
 295 @item @code{out}
 296 @tab @code{o}
 297 @item @code{bycopy}
 298 @tab @code{O}
 299 @item @code{oneway}
 300 @tab @code{V}
 301 @end multitable
 302
 303 @sp 1
 304
 305 The type specifiers are encoded just before the type. Unlike types
 306 however, the type specifiers are only encoded when they appear in method
 307 argument types.
 308
 309
 310 @node Garbage Collection, Constant string objects, Type encoding, Objective C
 311 @section Garbage Collection
 312
 313 Support for a new memory management policy has been added by using a
 314 powerful conservative garbage collector, known as the
 315 Boehm-Demers-Weiser conservative garbage collector. It is available from
 316 @w{@uref{http://www.hpl.hp.com/personal/Hans_Boehm/gc/}}.
 317
 318 To enable the support for it you have to configure the compiler using an
 319 additional argument, @w{@kbd{--enable-objc-gc}}. You need to have
 320 garbage collector installed before building the compiler. This will
 321 build an additional runtime library which has several enhancements to
 322 support the garbage collector. The new library has a new name,
 323 @kbd{libobjc_gc.a} to not conflict with the non-garbage-collected
 324 library.
 325
 326 When the garbage collector is used, the objects are allocated using the
 327 so-called typed memory allocation mechanism available in the
 328 Boehm-Demers-Weiser collector. This mode requires precise information on
 329 where pointers are located inside objects. This information is computed
 330 once per class, immediately after the class has been initialized.
 331
 332 There is a new runtime function @code{class_ivar_set_gcinvisible()}
 333 which can be used to declare a so-called @strong{weak pointer}
 334 reference. Such a pointer is basically hidden for the garbage collector;
 335 this can be useful in certain situations, especially when you want to
 336 keep track of the allocated objects, yet allow them to be
 337 collected. This kind of pointers can only be members of objects, you
 338 cannot declare a global pointer as a weak reference. Every type which is
 339 a pointer type can be declared a weak pointer, including @code{id},
 340 @code{Class} and @code{SEL}.
 341
 342 Here is an example of how to use this feature. Suppose you want to
 343 implement a class whose instances hold a weak pointer reference; the
 344 following class does this:
 345
 346 @example
 347
 348 @@interface WeakPointer : Object
 349 @{
 350     const void* weakPointer;
 351 @}
 352
 353 - initWithPointer:(const void*)p;
 354 - (const void*)weakPointer;
 355 @@end
 356
 357
 358 @@implementation WeakPointer
 359
 360 + (void)initialize
 361 @{
 362   class_ivar_set_gcinvisible (self, "weakPointer", YES);
 363 @}
 364
 365 - initWithPointer:(const void*)p
 366 @{
 367   weakPointer = p;
 368   return self;
 369 @}
 370
 371 - (const void*)weakPointer
 372 @{
 373   return weakPointer;
 374 @}
 375
 376 @@end
 377
 378 @end example
 379
 380 Weak pointers are supported through a new type character specifier
 381 represented by the @code{'!'} character. The
 382 @code{class_ivar_set_gcinvisible()} function adds or removes this
 383 specifier to the string type description of the instance variable named
 384 as argument.
 385
 386 @c =========================================================================
 387 @node Constant string objects
 388 @section Constant string objects
 389
 390 GNU Objective-C provides constant string objects that are generated
 391 directly by the compiler. You declare a constant string object by
 392 prefixing a C constant string with the character @code{@@}:
 393
 394 @example
 395   id myString = @@"this is a constant string object";
 396 @end example
 397
 398 The constant string objects are usually instances of the
 399 @code{NXConstantString} class which is provided by the GNU Objective-C
 400 runtime. To get the definition of this class you must include the
 401 @file{objc/NXConstStr.h} header file.
 402
 403 User defined libraries may want to implement their own constant string
 404 class. To be able to support them, the GNU Objective-C compiler provides
 405 a new command line options @code{-fconstant-string-class=<class
 406 name>}. The provided class should adhere to a strict structure, the same
 407 as @code{NXConstantString}'s structure:
 408
 409 @example
 410
 411 @@interface NXConstantString : Object
 412 @{
 413   char *c_string;
 414   unsigned int len;
 415 @}
 416 @@end
 417
 418 @end example
 419
 420 User class libraries may choose to inherit the customized constant
 421 string class from a different class than @code{Object}. There is no
 422 requirement in the methods the constant string class has to implement.
 423
 424 When a file is compiled with the @code{-fconstant-string-class} option,
 425 all the constant string objects will be instances of the class specified
 426 as argument to this option. It is possible to have multiple compilation
 427 units referring to different constant string classes, neither the
 428 compiler nor the linker impose any restrictions in doing this.