libobjc/objc-features.texi

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