chiark - git - mdw - sod/blob - lib/sod.3

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" The Sod runtime library
   4 .\"
   5 .\" (c) 2015 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the Sensible Object Design, an object system for C.
  11 .\"
  12 .\" SOD is free software; you can redistribute it and/or modify
  13 .\" it under the terms of the GNU Library General Public License as
  14 .\" published by the Free Software Foundation; either version 2 of the
  15 .\" License, or (at your option) any later version.
  16 .\"
  17 .\" SOD is distributed in the hope that it will be useful,
  18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 .\" GNU Library General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with SOD; if not, write to the Free
  24 .\" Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25 .\" MA 02111-1307, USA.
  26 .
  27 .\" Highlight using terminal escapes, rather than overstriking.
  28 .\"\X'tty: sgr 1'
  29 .
  30 .\" String definitions and font selection.
  31 .ie t \{\
  32 .  ds o \(bu
  33 .  if \n(.g .fam P
  34 .\}
  35 .el \{\
  36 .  ds o o
  37 .\}
  38 .
  39 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
  40 .de hP
  41 .IP
  42 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
  43 ..
  44 .
  45 .\"--------------------------------------------------------------------------
  46 .TH sod 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
  47 .
  48 .SH NAME
  49 sod \- Sensible Object Design runtime library
  50 .
  51 .\"--------------------------------------------------------------------------
  52 .SH SYNOPSIS
  53 .B #include <sod/sod.h>
  54 .PP
  55 .B void *\c
  56 .B SOD_XCHAIN(\c
  57 .IB chead ,
  58 .BI "const " cls " *" obj );
  59 .br
  60 .B ptrdiff_t
  61 .B SOD_OFFSETDIFF(\c
  62 .IB type ,
  63 .IB mema ,
  64 .IB memb );
  65 .br
  66 .IB cls "__ilayout *" \c
  67 .B SOD_ILAYOUT(\c
  68 .IB cls ,
  69 .IB chead ,
  70 .BI "const void *" obj );
  71 .br
  72 .B void *\c
  73 .B SOD_INSTBASE(\c
  74 .BI "const " cls " *" obj );
  75 .PP
  76 .B const void *\c
  77 .B SOD_CLASSOF(\c
  78 .BI "const " cls " *" obj );
  79 .br
  80 .B int
  81 .B sod_subclassp(\c
  82 .BI "const SodClass *" sub ,
  83 .BI "const SodClass *" super );
  84 .PP
  85 .IB cls " *" \c
  86 .B SOD_CONVERT(\c
  87 .IB cls ,
  88 .BI "const void *" obj );
  89 .br
  90 .B int
  91 .B sod_convert(\c
  92 .BI "const SodClass *" cls ,
  93 .BI "const void *" obj );
  94 .PP
  95 .IB cls " *" \c
  96 .B SOD_INIT(\c
  97 .IB cls ,
  98 .BI "void *" p ,
  99 .IB keywords );
 100 .br
 101 .B void *\c
 102 .B sod_init(\c
 103 .BI "const SodClass *" cls ,
 104 .BI "void *" p ,
 105 .B ...);
 106 .br
 107 .B void *\c
 108 .B sod_initv(\c
 109 .BI "const SodClass *" cls ,
 110 .BI "void *" p ,
 111 .BI "va_list " ap );
 112 .br
 113 .B SOD_DECL(\c
 114 .IB cls ,
 115 .IB var );
 116 .PP
 117 .
 118 .\"--------------------------------------------------------------------------
 119 .SH DESCRIPTION
 120 .
 121 The functions and macros defined here generally expect that
 122 instances and classes inherit from the standard
 123 .B SodObject
 124 root object.
 125 While the translator can (at some effort) support alternative roots,
 126 they will require different run-time support machinery.
 127 .
 128 .SS Layout utilities
 129 The following macros are useful in
 130 finding one's way around an instance layout structure,
 131 given various levels of information about
 132 what kind of object one is dealing with,
 133 or for computing the tables which are used for
 134 this kind of navigation.
 135 .PP
 136 These macros are mostly intended for use in
 137 code generated by the Sod translator.
 138 Others may find them useful for special effects,
 139 but they can be tricky to understand and use correctly
 140 and can't really be recommended for general use.
 141 .PP
 142 The
 143 .B SOD_OFFSETDIFF
 144 macro returns the signed offset between
 145 two members of a structure or union type.
 146 Given a structure or union type
 147 .IR type ,
 148 and two member names
 149 .I mema
 150 and
 151 .IR memb ,
 152 then
 153 .B SOD_OFFSETDIFF(\c
 154 .IB type ,
 155 .IB mema ,
 156 .IB memb )
 157 gives the difference, in bytes,
 158 between the objects
 159 .IB x . mema
 160 and
 161 .IB x . memb
 162 for any object
 163 .I x
 164 of type
 165 .IR type .
 166 This macro is used internally when generating vtables
 167 and is not expected to be very useful elsewhere.
 168 .PP
 169 The
 170 .B SOD_ILAYOUT
 171 macro recovers the instance layout base address
 172 from a pointer to one of its instance chains.
 173 Specifically, given a class name
 174 .IR cls ,
 175 the nickname
 176 .I chead
 177 of the least specific class in one of
 178 .IR cls 's
 179 superclass chains,
 180 and a pointer
 181 .I obj
 182 to the instance storage for the chain containing
 183 .I chead
 184 within an exact instance of
 185 .I cls
 186 (i.e., not an instance of any proper subclass),
 187 .B SOD_ILAYOUT(\c
 188 .IB cls ,
 189 .IB chead ,
 190 .IB obj )
 191 returns the a pointer to the layout structure containing
 192 .IB obj .
 193 This macro is used internally in effective method bodies
 194 and is not expected to be very useful elsewhere
 195 since it's unusual to have such specific knowledge
 196 about the dynamic type of an instance.
 197 The
 198 .B SOD_INSTBASE
 199 macro (described below) is more suited to general use.
 200 .PP
 201 The
 202 .B SOD_INSTBASE
 203 macro finds the base address of an instance's layout.
 204 Given a pointer
 205 .BI "const " cls " *" obj
 206 to an instance,
 207 .BI SOD_INSTBASE( obj )
 208 returns the base address of the storage allocated to
 209 .IR obj .
 210 This is useful if you want to free a dynamically allocated instance,
 211 for example.
 212 This macro needs to look up an offset in
 213 .IR obj 's
 214 vtable to do its work.
 215 Compare
 216 .B SOD_ILAYOUT
 217 above,
 218 which is faster but requires
 219 precise knowledge of the instance's dynamic class.
 220 .
 221 .SS Classes
 222 The following macros and functions
 223 query the runtime relationhips between
 224 instances and classes.
 225 .PP
 226 The
 227 .B SOD_CLASSOF
 228 macro returns the class object describing an instance's dynamic class.
 229 Given a pointer
 230 .BI "const " cls " *" obj
 231 to an instance,
 232 .BI SOD_CLASSOF( obj )
 233 returns a pointer to
 234 .IR obj 's
 235 dynamic class,
 236 which
 237 (assuming
 238 .I obj
 239 is typed correctly in the first place)
 240 will be a subclass of
 241 .IR cls .
 242 (If you wanted the class object for
 243 .I cls
 244 itself,
 245 it's called
 246 .IB cls __class \fR.)
 247 .PP
 248 The
 249 .B sod_subclassp
 250 function answers whether one class
 251 .I sub
 252 is actually a subclass of another class
 253 .IR super .
 254 .B sod_subclassp(\c
 255 .IB sub ,
 256 .IB super )
 257 returns nonzero if and only if
 258 .I sub
 259 is a subclass of
 260 .IR super .
 261 This involves a run-time trawl through the class structures:
 262 while some effort has been made to make it perform well
 263 it's still not very fast.
 264 .
 265 .SS Conversions
 266 The following macros and functions are used
 267 to convert instance pointers of some (static) type
 268 into instance pointers of other static types
 269 to the same instance.
 270 .PP
 271 The
 272 .B SOD_XCHAIN
 273 macro performs a `cross-chain upcast'.
 274 Given a pointer
 275 .I cls
 276 .BI * obj
 277 to an instance of a class of type
 278 .I cls
 279 and the nickname
 280 .I chead
 281 of the least specific class in one of
 282 .IR cls 's
 283 superclass chains which does not contain
 284 .I cls
 285 itself,
 286 .B SOD_XCHAIN(\c
 287 .IB chead ,
 288 .IB obj )
 289 returns the address of that chain's storage
 290 within the instance layout as a raw
 291 .B void *
 292 pointer.
 293 (Note that
 294 .I cls
 295 is not mentioned explicitly.)
 296 This macro is used by the generated
 297 .IB cls __CONV_ c
 298 conversion macros,
 299 which you are encouraged to use instead where possible.
 300 .PP
 301 The
 302 .B SOD_CONVERT
 303 macro
 304 and
 305 .B sod_convert
 306 function
 307 perform general conversions
 308 (up-, down-, and cross-casts) on instance pointers.
 309 Given a class
 310 .I cls
 311 and a pointer
 312 .BI "const void *" obj
 313 to an instance,
 314 they return an appropriately converted pointer to
 315 .I obj
 316 if
 317 .I obj
 318 is indeed an instance of (some subclass of)
 319 .IR cls ;
 320 otherwise they return a null pointer.
 321 .PP
 322 The
 323 .B SOD_CONVERT
 324 macro expects
 325 .I cls
 326 to be a class name;
 327 the
 328 .B sod_convert
 329 function
 330 expects a pointer to a class object instead.
 331 .PP
 332 This involves a run-time trawl through the class structures:
 333 while some effort has been made to make it perform well
 334 it's still not very fast.
 335 For upcasts (where
 336 .I cls
 337 is a superclass of the static type of
 338 .IR obj )
 339 the automatically defined conversion macros should be used instead,
 340 because they're much faster and can't fail.
 341 .PP
 342 When the target class is known statically,
 343 it's slightly more convenient to use the
 344 .B SOD_CONVERT
 345 macro rather than the
 346 .B sod_convert
 347 function,
 348 since the class object name is longer and uglier,
 349 and the macro returns a pointer of the correct type.
 350 .
 351 .SS Instance lifecycle
 352 The following macros and functions
 353 manage the standard steps along
 354 an instance's lifecycle.
 355 .PP
 356 The
 357 .B SOD_INIT
 358 macro,
 359 and the
 360 .B sod_init
 361 and
 362 .B sod_initv
 363 functions,
 364 imprint and initialize an instance of a class
 365 .I cls
 366 in the storage starting at address
 367 .IR p .
 368 .PP
 369 The direct class for the new instance is specified as
 370 a class name to
 371 .BR SOD_INIT ,
 372 or a pointer to a class object to the functions.
 373 .PP
 374 Keyword arguments for the initialization message may be provided.
 375 The
 376 .B SOD_INIT
 377 macro expects a single preprocessor-time argument
 378 which is a use of one of
 379 .B KWARGS
 380 or
 381 .B NO_KWARGS
 382 (see
 383 .BR keyword (3));
 384 the
 385 .B sod_init
 386 function expects the keywords as
 387 a variable-length argument tail;
 388 and
 389 .B sod_initv
 390 expects the keywords to be passed indirectly,
 391 through the captured argument-tail cursor
 392 .IR ap .
 393 .PP
 394 The return value is an instance pointer for the class
 395 .IR cls ;
 396 the
 397 .B SOD_INIT
 398 macro will have converted it to the correct type,
 399 so it should probably be used where possible.
 400 In fact, this is guaranteed to be equal to
 401 .I p
 402 by the layout rules described in
 403 .BR sod-structs (3).
 404 .PP
 405 The
 406 .B SOD_DECL
 407 macro declares and initializes an instance
 408 with automatic storage duration.
 409 Given a class name
 410 .I cls
 411 and an identifier
 412 .IR var ,
 413 .B SOD_DECL(\c
 414 .IB cls ,
 415 .IB var )
 416 declares
 417 .I var
 418 to be a pointer to an instance of
 419 .IR cls .
 420 The instance is initialized in the sense that
 421 its vtable and class pointers have been set up,
 422 and slots for which initializers are defined
 423 are set to the appropriate initial values.
 424 The instance has automatic storage duration:
 425 pointers to it will become invalid when control
 426 exits the scope of the declaration.
 427 .
 428 .\"--------------------------------------------------------------------------
 429 .SH SEE ALSO
 430 .BR keyword (3),
 431 .BR sod (1),
 432 .BR sod-structs (3).
 433 .
 434 .\"--------------------------------------------------------------------------
 435 .SH AUTHOR
 436 Mark Wooding, <mdw@distorted.org.uk>
 437 .
 438 .\"----- That's all, folks --------------------------------------------------