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