mdw@git.distorted.org.uk Git - 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 void
 114 .B sod_teardown(\c
 115 .BI "void *" p );
 116 .br
 117 .B SOD_DECL(\c
 118 .IB cls ,
 119 .IB var );
 120 .br
 121 .IB cls " *" \c
 122 .B SOD_MAKE(\c
 123 .IB cls ,
 124 .IB keywords );
 125 .br
 126 .B void *\c
 127 .B sod_make(\c
 128 .BI "const SodClass *" cls ,
 129 .B ...);
 130 .br
 131 .B void *\c
 132 .B sod_makev(\c
 133 .BI "const SodClass *" cls ,
 134 .BI "va_list " ap );
 135 .br
 136 .B int
 137 .B sod_destroy(\c
 138 .BI "void *" p );
 139 .PP
 140 .
 141 .\"--------------------------------------------------------------------------
 142 .SH DESCRIPTION
 143 .
 144 The functions and macros defined here generally expect that
 145 instances and classes inherit from the standard
 146 .B SodObject
 147 root object.
 148 While the translator can (at some effort) support alternative roots,
 149 they will require different run-time support machinery.
 150 .
 151 .SS Layout utilities
 152 The following macros are useful in
 153 finding one's way around an instance layout structure,
 154 given various levels of information about
 155 what kind of object one is dealing with,
 156 or for computing the tables which are used for
 157 this kind of navigation.
 158 .PP
 159 These macros are mostly intended for use in
 160 code generated by the Sod translator.
 161 Others may find them useful for special effects,
 162 but they can be tricky to understand and use correctly
 163 and can't really be recommended for general use.
 164 .PP
 165 The
 166 .B SOD_OFFSETDIFF
 167 macro returns the signed offset between
 168 two members of a structure or union type.
 169 Given a structure or union type
 170 .IR type ,
 171 and two member names
 172 .I mema
 173 and
 174 .IR memb ,
 175 then
 176 .B SOD_OFFSETDIFF(\c
 177 .IB type ,
 178 .IB mema ,
 179 .IB memb )
 180 gives the difference, in bytes,
 181 between the objects
 182 .IB x . mema
 183 and
 184 .IB x . memb
 185 for any object
 186 .I x
 187 of type
 188 .IR type .
 189 This macro is used internally when generating vtables
 190 and is not expected to be very useful elsewhere.
 191 .PP
 192 The
 193 .B SOD_ILAYOUT
 194 macro recovers the instance layout base address
 195 from a pointer to one of its instance chains.
 196 Specifically, given a class name
 197 .IR cls ,
 198 the nickname
 199 .I chead
 200 of the least specific class in one of
 201 .IR cls 's
 202 superclass chains,
 203 and a pointer
 204 .I obj
 205 to the instance storage for the chain containing
 206 .I chead
 207 within an exact instance of
 208 .I cls
 209 (i.e., not an instance of any proper subclass),
 210 .B SOD_ILAYOUT(\c
 211 .IB cls ,
 212 .IB chead ,
 213 .IB obj )
 214 returns the a pointer to the layout structure containing
 215 .IB obj .
 216 This macro is used internally in effective method bodies
 217 and is not expected to be very useful elsewhere
 218 since it's unusual to have such specific knowledge
 219 about the dynamic type of an instance.
 220 The
 221 .B SOD_INSTBASE
 222 macro (described below) is more suited to general use.
 223 .PP
 224 The
 225 .B SOD_INSTBASE
 226 macro finds the base address of an instance's layout.
 227 Given a pointer
 228 .BI "const " cls " *" obj
 229 to an instance,
 230 .BI SOD_INSTBASE( obj )
 231 returns the base address of the storage allocated to
 232 .IR obj .
 233 This is useful if you want to free a dynamically allocated instance,
 234 for example.
 235 This macro needs to look up an offset in
 236 .IR obj 's
 237 vtable to do its work.
 238 Compare
 239 .B SOD_ILAYOUT
 240 above,
 241 which is faster but requires
 242 precise knowledge of the instance's dynamic class.
 243 .
 244 .SS Classes
 245 The following macros and functions
 246 query the runtime relationhips between
 247 instances and classes.
 248 .PP
 249 The
 250 .B SOD_CLASSOF
 251 macro returns the class object describing an instance's dynamic class.
 252 Given a pointer
 253 .BI "const " cls " *" obj
 254 to an instance,
 255 .BI SOD_CLASSOF( obj )
 256 returns a pointer to
 257 .IR obj 's
 258 dynamic class,
 259 which
 260 (assuming
 261 .I obj
 262 is typed correctly in the first place)
 263 will be a subclass of
 264 .IR cls .
 265 (If you wanted the class object for
 266 .I cls
 267 itself,
 268 it's called
 269 .IB cls __class \fR.)
 270 .PP
 271 The
 272 .B sod_subclassp
 273 function answers whether one class
 274 .I sub
 275 is actually a subclass of another class
 276 .IR super .
 277 .B sod_subclassp(\c
 278 .IB sub ,
 279 .IB super )
 280 returns nonzero if and only if
 281 .I sub
 282 is a subclass of
 283 .IR super .
 284 This involves a run-time trawl through the class structures:
 285 while some effort has been made to make it perform well
 286 it's still not very fast.
 287 .
 288 .SS Conversions
 289 The following macros and functions are used
 290 to convert instance pointers of some (static) type
 291 into instance pointers of other static types
 292 to the same instance.
 293 .PP
 294 The
 295 .B SOD_XCHAIN
 296 macro performs a `cross-chain upcast'.
 297 Given a pointer
 298 .I cls
 299 .BI * obj
 300 to an instance of a class of type
 301 .I cls
 302 and the nickname
 303 .I chead
 304 of the least specific class in one of
 305 .IR cls 's
 306 superclass chains which does not contain
 307 .I cls
 308 itself,
 309 .B SOD_XCHAIN(\c
 310 .IB chead ,
 311 .IB obj )
 312 returns the address of that chain's storage
 313 within the instance layout as a raw
 314 .B void *
 315 pointer.
 316 (Note that
 317 .I cls
 318 is not mentioned explicitly.)
 319 This macro is used by the generated
 320 .IB cls __CONV_ c
 321 conversion macros,
 322 which you are encouraged to use instead where possible.
 323 .PP
 324 The
 325 .B SOD_CONVERT
 326 macro
 327 and
 328 .B sod_convert
 329 function
 330 perform general conversions
 331 (up-, down-, and cross-casts) on instance pointers.
 332 Given a class
 333 .I cls
 334 and a pointer
 335 .BI "const void *" obj
 336 to an instance,
 337 they return an appropriately converted pointer to
 338 .I obj
 339 if
 340 .I obj
 341 is indeed an instance of (some subclass of)
 342 .IR cls ;
 343 otherwise they return a null pointer.
 344 .PP
 345 The
 346 .B SOD_CONVERT
 347 macro expects
 348 .I cls
 349 to be a class name;
 350 the
 351 .B sod_convert
 352 function
 353 expects a pointer to a class object instead.
 354 .PP
 355 This involves a run-time trawl through the class structures:
 356 while some effort has been made to make it perform well
 357 it's still not very fast.
 358 For upcasts (where
 359 .I cls
 360 is a superclass of the static type of
 361 .IR obj )
 362 the automatically defined conversion macros should be used instead,
 363 because they're much faster and can't fail.
 364 .PP
 365 When the target class is known statically,
 366 it's slightly more convenient to use the
 367 .B SOD_CONVERT
 368 macro rather than the
 369 .B sod_convert
 370 function,
 371 since the class object name is longer and uglier,
 372 and the macro returns a pointer of the correct type.
 373 .
 374 .SS Instance lifecycle
 375 The following macros and functions
 376 manage the standard steps along
 377 an instance's lifecycle.
 378 .PP
 379 The
 380 .B SOD_INIT
 381 macro,
 382 and the
 383 .B sod_init
 384 and
 385 .B sod_initv
 386 functions,
 387 imprint and initialize an instance of a class
 388 .I cls
 389 in the storage starting at address
 390 .IR p .
 391 .PP
 392 The direct class for the new instance is specified as
 393 a class name to
 394 .BR SOD_INIT ,
 395 or a pointer to a class object to the functions.
 396 .PP
 397 Keyword arguments for the initialization message may be provided.
 398 The
 399 .B SOD_INIT
 400 macro expects a single preprocessor-time argument
 401 which is a use of one of
 402 .B KWARGS
 403 or
 404 .B NO_KWARGS
 405 (see
 406 .BR keyword (3));
 407 the
 408 .B sod_init
 409 function expects the keywords as
 410 a variable-length argument tail;
 411 and
 412 .B sod_initv
 413 expects the keywords to be passed indirectly,
 414 through the captured argument-tail cursor
 415 .IR ap .
 416 .PP
 417 The return value is an instance pointer for the class
 418 .IR cls ;
 419 the
 420 .B SOD_INIT
 421 macro will have converted it to the correct type,
 422 so it should probably be used where possible.
 423 In fact, this is guaranteed to be equal to
 424 .I p
 425 by the layout rules described in
 426 .BR sod-structs (3).
 427 .PP
 428 The
 429 .B sod_teardown
 430 function tears down an instance of a class,
 431 releasing any resources it holds.
 432 .PP
 433 This function is a very thin wrapper around sending the
 434 .B obj.teardown
 435 message.
 436 It returns an integer flag.
 437 A zero value means that the instance is safe to deallocate.
 438 A nonzero value means that the instance should not be deallocated,
 439 and that it is safe for the caller to simply forget about it.
 440 (For example, the object may maintain a reference count,
 441 and knows that other references remain active.)
 442 .PP
 443 The
 444 .B SOD_DECL
 445 macro declares and initializes an instance
 446 with automatic storage duration.
 447 Given a class name
 448 .I cls
 449 and an identifier
 450 .IR var ,
 451 .B SOD_DECL(\c
 452 .IB cls ,
 453 .IB var )
 454 declares
 455 .I var
 456 to be a pointer to an instance of
 457 .IR cls .
 458 The instance is initialized in the sense that
 459 its vtable and class pointers have been set up,
 460 and slots for which initializers are defined
 461 are set to the appropriate initial values.
 462 The instance has automatic storage duration:
 463 pointers to it will become invalid when control
 464 exits the scope of the declaration.
 465 .PP
 466 Keyword arguments for the initialization message may be provided.
 467 The macro expects a single preprocessor-time argument
 468 which is a use of one of
 469 .B KWARGS
 470 or
 471 .B NO_KWARGS
 472 (see
 473 .BR keyword (3)).
 474 .PP
 475 The instance has automatic storage duration:
 476 pointers to it will become invalid
 477 when control exits the scope of the declaration.
 478 If necessary,
 479 the instance should be torn down before this happens,
 480 using the
 481 .B sod_teardown
 482 function.
 483 It may be appropriate to
 484 .BR assert (3)
 485 that the object is ready for deallocation at this time.
 486 .PP
 487 The
 488 .B SOD_MAKE
 489 macro,
 490 and the
 491 .B sod_make
 492 and
 493 .B sod_makev
 494 functions,
 495 construct and return a pointer to a new instance of a class.
 496 .PP
 497 The direct class for the new instance is specified as a class name to
 498 .BR SOD_MAKE ,
 499 or as a class object to the functions.
 500 .PP
 501 Keyword arguments for the initialization message may be provided.
 502 The
 503 .B SOD_MAKE
 504 macro expects a single preprocessor-time argument
 505 which is a use of one of
 506 .B KWARGS
 507 or
 508 .B NO_KWARGS
 509 (see
 510 .BR keyword (3));
 511 the
 512 .B sod_init
 513 function expects the keywords as
 514 a variable-length argument tail;
 515 and
 516 .B sod_makev
 517 expects the keywords to be passed indirectly,
 518 through the captured argument-tail cursor
 519 .IR ap .
 520 .PP
 521 Storage for the new instance will have been allocated
 522 using the standard
 523 .BR malloc (3)
 524 function.
 525 The easiest way to destroy the instance,
 526 when it is no longer needed,
 527 is probably to call the
 528 .B sod_destroy
 529 function.
 530 .PP
 531 The return value is an instance pointer for the class
 532 .IR cls ;
 533 the
 534 .B SOD_MAKE
 535 macro will have converted it to the correct type,
 536 so it should probably be used where possible.
 537 .PP
 538 The
 539 .B sod_destroy
 540 function tears down and frees an instance allocated using
 541 .BR malloc (3).
 542 .PP
 543 The pointer
 544 .I p
 545 should be an instance pointer,
 546 i.e., a pointer to any of an instance's chains.
 547 The instance is torn down,
 548 by sending it the
 549 .B obj.teardown
 550 message.
 551 If the instance reports itself ready for deallocation,
 552 then its storage is released using
 553 .BR free (3).
 554 The return value is the value returned by the
 555 .B obj.teardown
 556 message.
 557 .
 558 .\"--------------------------------------------------------------------------
 559 .SH SEE ALSO
 560 .BR keyword (3),
 561 .BR sod (1),
 562 .BR sod-structs (3).
 563 .
 564 .\"--------------------------------------------------------------------------
 565 .SH AUTHOR
 566 Mark Wooding, <mdw@distorted.org.uk>
 567 .
 568 .\"----- That's all, folks --------------------------------------------------