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