mdw@git.distorted.org.uk Git - sod/blob - lib/sod.3.in

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