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

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Description of the main Sod data structures
   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-structs 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
  32 .
  33 .SH NAME
  34 sod-structs \- main Sod data structures
  35 .
  36 .\"--------------------------------------------------------------------------
  37 .SH SYNOPSIS
  38 .nf
  39 .ft B
  40 #include <sod/sod.h>
  41
  42 typedef struct SodObject__ichain_obj SodObject;
  43 typedef struct SodClass__ichain_obj SodClass;
  44
  45 struct sod_instance {
  46 \h'2n'const struct sod_vtable *_vt;
  47 };
  48
  49 struct sod_vtable {
  50 \h'2n'const SodClass *_class;
  51 \h'2n'size_t _base;
  52 };
  53
  54 struct SodObject__vt_obj {
  55 \h'2n'const SodClass *_class;
  56 \h'2n'size_t _base;
  57 \h'2n'struct SodObject__vtmsgs_obj {
  58 \h'4n'void (*init)(SodObject *\fIme\fB, ...);
  59 \h'4n'void (*init__v)(SodObject *\fIme\fB, va_list);
  60 \h'4n'int (*teardown)(SodObject *\fIme\fB);
  61 \h'2n'} obj;
  62 };
  63
  64 struct SodObject__ilayout {
  65 \h'2n'union {
  66 \h'4n'struct SodObject__ichain_obj {
  67 \h'6n'const struct SodObject__vt_obj *_vt;
  68 \h'4n'};
  69 \h'2n'} obj;
  70 };
  71
  72 extern const struct SodClass__ilayout SodObject__classobj;
  73 #define SodObject__class (&SodObject__classobj.obj.cls)
  74
  75 struct SodClass__vt_obj {
  76 \h'2n'const SodClass *_class;
  77 \h'2n'size_t _base;
  78 \h'2n'struct SodClass__vtmsgs_obj {
  79 \h'4n'void (*init)(SodClass *\fIme\fB, ...);
  80 \h'4n'void (*init__v)(SodClass *\fIme\fB, va_list);
  81 \h'4n'int (*teardown)(SodClass *\fIme\fB);
  82 \h'2n'} obj;
  83 };
  84
  85 struct SodClass__ilayout {
  86 \h'2n'union {
  87 \h'4n'struct SodClass__ichain_obj {
  88 \h'6n'const struct SodClass__vt_obj *_vt;
  89 \h'6n'struct SodClass__islots {
  90 \h'8n'const char *name;
  91 \h'8n'const char *nick;
  92 \h'8n'size_t initsz;
  93 \h'8n'size_t align;
  94 \h'8n'void *(*imprint)(void *\fIp\fB);
  95 \h'8n'size_t n_supers;
  96 \h'8n'const SodClass *const *supers;
  97 \h'8n'size_t n_cpl;
  98 \h'8n'const SodClass *const *cpl;
  99 \h'8n'const SodClass *link;
 100 \h'8n'const SodClass *head;
 101 \h'8n'size_t level;
 102 \h'8n'size_t n_chains;
 103 \h'8n'const struct sod_chain *chains;
 104 \h'8n'size_t off_islots;
 105 \h'8n'size_t islotsz;
 106 \h'6n'} cls;
 107 \h'4n'};
 108 \h'4n'SodObject obj;
 109 \h'2n'} obj;
 110 };
 111
 112 struct sod_chain {
 113 \h'2n'size_t n_classes;
 114 \h'2n'const SodClass *const *classes;
 115 \h'2n'size_t off_ichain;
 116 \h'2n'const struct sod_vtable *vt;
 117 \h'2n'size_t ichainsz;
 118 };
 119
 120 extern const struct SodClass__ilayout SodClass__classobj;
 121 #define SodClass__class (&SodClass__classobj.obj.cls)
 122 .fi
 123 .ft P
 124 .
 125 .\"--------------------------------------------------------------------------
 126 .SH DESCRIPTION
 127 .
 128 This page describes the structure and layout
 129 of standard Sod objects, classes and associated metadata.
 130 Note that Sod's object system is very flexible
 131 and it's possible for an extension
 132 to define a new root class
 133 which works very differently from the standard
 134 .B SodObject
 135 described here.
 136 .
 137 .\"--------------------------------------------------------------------------
 138 .SH COMMON INSTANCE STRUCTURE
 139 .
 140 As described below,
 141 a pointer to an instance actually points to an
 142 .I "instance chain"
 143 structure within the instances overall layout structure.
 144 .PP
 145 Instance chains contain slots and vtable pointers,
 146 as described below.
 147 All instances have the basic structure of a
 148 .BR "struct sod_instance" ,
 149 which has the following members.
 150 .TP
 151 .B "const struct sod_vtable *_vt"
 152 A pointer to a
 153 .IR vtable ,
 154 which has the basic structure of a
 155 .BR "struct sod_vtable" ,
 156 described below.
 157 .PP
 158 A vtable contains static metadata needed
 159 for efficient conversions and
 160 message dispatch,
 161 and pointers to the instance's class.
 162 Each chain points to a different vtable
 163 All vtables have the basic structure of a
 164 .BR "struct sod_vtable" ,
 165 which has the following members.
 166 .TP
 167 .B "const SodClass *_class"
 168 A pointer to the instance's class object.
 169 .TP
 170 .B "size_t _base;"
 171 The offset of this chain structure
 172 above the start of the overall instance layout, in bytes.
 173 Subtracting
 174 .B _base
 175 from the instance chain pointer
 176 finds the layout base address.
 177 .
 178 .\"--------------------------------------------------------------------------
 179 .SH BUILT-IN ROOT OBJECTS
 180 .
 181 This section describes the built-in classes
 182 .B SodObject
 183 and
 184 .BR SodClass ,
 185 which are the standard roots of the inheritance and metaclass graphs
 186 respectively.
 187 Specifically,
 188 .B SodObject
 189 has no direct superclasses,
 190 and
 191 .B SodClass
 192 is its own metaclass.
 193 It is not possible to define root classes in module files
 194 because of circularities:
 195 .B SodObject
 196 has
 197 .B SodClass
 198 as its metaclass,
 199 and
 200 .B SodClass
 201 is a subclass of
 202 .BR SodObject .
 203 Extensions can define additional root classes,
 204 but this is tricky,
 205 and not really to be recommended.
 206 .
 207 .SS The SodObject class
 208 The
 209 .B SodObject
 210 class defines no slots.
 211 Because
 212 .B SodObject
 213 has no direct superclasses,
 214 there is only one chain,
 215 and no inherited slots or messages,
 216 so the single chain contains only a vtable pointer.
 217 .PP
 218 Since
 219 .B SodClass
 220 also has only one chain,
 221 the vtable contains only the standard class pointer and offset-to-base
 222 members.
 223 In an actual instance of
 224 .B SodObject
 225 (why would you want one?)
 226 the class pointer contains the address of
 227 .B SodObject__class
 228 and the offset is zero.
 229 .PP
 230 The
 231 .B init
 232 message is used to initialize a newly allocated instance.
 233 .PP
 234 This message uses a custom method combination
 235 which works like the standard method combination
 236 except that default behaviour
 237 specific to the receiver's direct class
 238 is invoked if no primary or around method overrides.
 239 This default behaviour may be invoked multiple times
 240 if some method calls on its
 241 .B next_method
 242 function more than once.
 243 .PP
 244 This default behaviour is to initialize the instance's slots
 245 using the defined slot initializers,
 246 and execute the initialization fragments.
 247 Each slot is initialized
 248 using the most specific applicable initializer,
 249 if any.
 250 Slots without an initializer
 251 are left uninitialized.
 252 .PP
 253 Slots are initialized and initialization fragments executed together,
 254 a superclass at a time:
 255 first, the superclass's slots are initialized (if any);
 256 then the superclass's initialization fragments (if any) are executed,
 257 starting with the least specific superclass first.
 258 Slots and initialization fragments defined by the same class
 259 are processed in the order in which they appear in the class definition.
 260 .PP
 261 There are no standard keyword arguments;
 262 methods on subclasses are free to
 263 introduce their own in the usual way.
 264 .PP
 265 It is usual to provide complex initialization behaviour as
 266 .B after
 267 methods.
 268 This ensures that slots have been initialized as necessary
 269 before the method executes.
 270 .PP
 271 The
 272 .B teardown
 273 message is used to tear down an instance which is no longer required.
 274 .PP
 275 The message returns an integer flag.
 276 A zero value means that the instance is safe to deallocate.
 277 A nonzero value means that the instance should not be deallocated,
 278 and that it is safe for the caller to simply forget about it.
 279 This simple protocol may be used, for example,
 280 to implement a reference-counting system.
 281 .PP
 282 This message uses a custom method combination
 283 which works like the standard method combination
 284 except that default behaviour is invoked if
 285 no primary or around method overrides.
 286 This default behaviour is to execute
 287 each superclass's teardown fragments,
 288 most specific first,
 289 and then return zero to indicate
 290 that the object is ready for deallocation.
 291 Teardown fragments defined by the same class
 292 are processed in the order in which they appear
 293 in the class definition.
 294 .PP
 295 It is usual to provide complex teardown behaviour as
 296 .B before
 297 methods.
 298 Logic to decide whether to allow deallocation
 299 is usually implemented as
 300 .B around
 301 methods.
 302 .
 303 .SS The SodClass class
 304 The
 305 .B SodClass
 306 class defines no messages,
 307 but there are a number of slots.
 308 Its only direct superclass is
 309 .B SodObject
 310 and so (like its superclass) its vtable is trivial.
 311 .PP
 312 The slots defined are as follows.
 313 .TP
 314 .B const char *name;
 315 A pointer to the class's name.
 316 .TP
 317 .B const char *nick;
 318 A pointer to the class's nickname.
 319 .TP
 320 .B size_t initsz;
 321 The size in bytes required to store an instance of the class.
 322 .TP
 323 .B size_t align;
 324 A sufficient alignment for the class's instance storage.
 325 .TP
 326 .BI "void *(*imprint)(void *" p );
 327 A pointer to a function:
 328 given a pointer
 329 .I p
 330 to at least
 331 .I initsz
 332 bytes of appropriately aligned memory,
 333 `imprint' this memory it so that it becomes a minimally functional
 334 instance of the class:
 335 all of the vtable and class pointers are properly initialized,
 336 but the slots are left untouched.
 337 The function returns its argument
 338 .IR p .
 339 .TP
 340 .B size_t n_supers;
 341 The number of direct superclasses.
 342 (This is zero exactly in the case of
 343 .BR SodObject .)
 344 .TP
 345 .B const SodClass *const *supers;
 346 A pointer to an array of
 347 .I n_supers
 348 pointers to class objects
 349 listing the class's direct superclasses,
 350 in the order in which they were listed in the class definition.
 351 If
 352 .I n_supers
 353 is zero,
 354 then this pointer is null.
 355 .TP
 356 .B size_t n_cpl;
 357 The number of superclasses in the class's class precedence list.
 358 .TP
 359 .B const SodClass *const *cpl;
 360 A pointer to an array of pointers to class objects
 361 listing all of the class's superclasses,
 362 from most- to least-specific,
 363 starting with the class itself,
 364 so
 365 .IB c ->cls.cpl[0]
 366 =
 367 .I c
 368 for all class objects
 369 .IR c .
 370 .TP
 371 .B const SodClass *link;
 372 If the class is a chain head, then this is a null pointer;
 373 otherwise it points to the class's distinguished link superclass
 374 (which might or might not be a direct superclass).
 375 .TP
 376 .B const SodClass *head;
 377 A pointer to the least-specific class in this class's chain;
 378 so
 379 .IB c ->cls.head->cls.link
 380 is always null,
 381 and either
 382 .IB c ->cls.link
 383 is null
 384 (in which case
 385 .IB c ->cls.head
 386 =
 387 .IR c )
 388 or
 389 .IB c ->cls.head
 390 =
 391 .IB c ->cls.link->cls.head \fR.
 392 .TP
 393 .B size_t level;
 394 The number of less specific superclasses in this class's chain.
 395 If
 396 .IB c ->cls.link
 397 is null then
 398 .IB c ->cls.level
 399 is zero;
 400 otherwise
 401 .IB c ->cls.level
 402 =
 403 .IB c ->cls.link->cls.level
 404 + 1.
 405 .TP
 406 .B size_t n_chains;
 407 The number of chains formed by the class's superclasses.
 408 .TP
 409 .B const struct sod_chain *chains;
 410 A pointer to an array of
 411 .B struct sod_chain
 412 structures (see below) describing the class's superclass chains,
 413 in decreasing order of specificity of their most specific classes.
 414 It is always the case that
 415 .IB c ->cls.chains[0].classes[ c ->cls.level]
 416 =
 417 .IR c .
 418 .TP
 419 .B size_t off_islots;
 420 The offset of the class's
 421 .B islots
 422 structure relative to its containing
 423 .B ichain
 424 structure.
 425 The class doesn't define any slots if and only if this is zero.
 426 (The offset can't be zero because the vtable pointer is at offset zero.)
 427 .TP
 428 .B size_t islotsz;
 429 The size required to store the class's direct slots,
 430 i.e., the size of its
 431 .B islots
 432 structure.
 433 The class doesn't define any slots if and only if this is zero.
 434 .PP
 435 The
 436 .B struct sod_chain
 437 structure describes an individual chain of superclasses.
 438 It has the following members.
 439 .TP
 440 .B size_t n_classes;
 441 The number of classes in the chain.
 442 This is always at least one.
 443 .TP
 444 .B const SodClass *const *classes;
 445 A pointer to an array of class pointers
 446 listing the classes in the chain from least- to most-specific.
 447 So
 448 .IB classes [ i ]->cls.head
 449 =
 450 .IB classes [0]
 451 for all
 452 0 \(<=
 453 .I i
 454 <
 455 .IR n_classes ,
 456 .IB classes [0]->cls.link
 457 is always null,
 458 and
 459 .IB classes [ i ]->cls.link
 460 =
 461 .IB classes [ "i\fR \- 1" ]
 462 if
 463 1 \(<=
 464 .I i
 465 <
 466 .IR n_classes .
 467 .TP
 468 .B size_t off_ichain;
 469 The size of the
 470 .B ichain
 471 structure for this chain.
 472 .TP
 473 .B const struct sod_vtable *vt;
 474 The vtable for this chain.
 475 (It is possible, therefore, to duplicate the behaviour of the
 476 .I imprint
 477 function by walking the chain structure.
 478 The
 479 .I imprint
 480 function is much faster, though.)
 481 .TP
 482 .B size_t ichainsz;
 483 The size of the
 484 .B ichain
 485 structure for this chain.
 486 .
 487 .\"--------------------------------------------------------------------------
 488 .SH CLASS AND VTABLE LAYOUT
 489 .
 490 The layout algorithms for Sod instances and vtables are nontrivial.
 491 They are defined here in full detail,
 492 since they're effectively fixed by Sod's ABI compatibility guarantees,
 493 so they might as well be documented for the sake of interoperating
 494 programs.
 495 .PP
 496 Unfortunately, the descriptions are rather complicated,
 497 and, for the most part not necessary to a working understanding of Sod.
 498 The skeleton structure definitions shown should be more than enough
 499 for readers attempting to make sense of the generated headers and tables.
 500 .PP
 501 In the description that follows,
 502 uppercase letters vary over class names,
 503 while the corresponding lowercase letters indicate the class nicknames.
 504 Throughout, we consider a class
 505 .I C
 506 (therefore with nickname
 507 .IR c ).
 508 .
 509 .SS Generic instance structure
 510 The entire state of an instance of
 511 .I C
 512 is contained in a single structure of type
 513 .B struct
 514 .IB C __ilayout \fR.
 515 .VS
 516 struct \fIC\fB__ilayout {
 517 \h'2n'union \fIC\fB__ichainu_\fIh\fB {
 518 \h'4n'struct \fIC\fB__ichain_\fIh\fB {
 519 \h'6n'const struct \fIC\fB__vt_\fIh\fB *_vt;
 520 \h'6n'struct \fIH\fB__islots \fIh\fB;
 521 \h'6n'\fR...\fB
 522 \h'6n'struct \fIC\fB__islots {
 523 \h'8n'\fItype\fB \fIslota\fB;
 524 \h'8n'\fR...\fB
 525 \h'6n'} \fIc\fB;
 526 \h'4n'} \fIc\fB;
 527 \h'4n'\fR...\fB
 528 \h'4n'struct \fIA\fB__ichain_\fIh\fB \fIa\fB;
 529 \h'2n'} \fIh\fB;
 530 \h'2n'union \fIB\fB__ichainu_\fIi\fB \fIi\fB;
 531 \h'2n'\fR...\fB
 532 };
 533
 534 typedef struct \fIC\fB__ichain_\fIh\fB \fIC\fB;
 535 .VE
 536 The set of superclasses of
 537 .IR C ,
 538 including itself,
 539 can be partitioned into chains
 540 by following their distinguished superclass links.
 541 (Formally, the chains are the equivalence classes determined by
 542 the reflexive, symmetric, transitive closure of
 543 the `links to' relation.)
 544 Chains are identified by naming their least specific classes;
 545 the least specific class in a chain is called the
 546 .IR "chain head" .
 547 Suppose that the chain head of the chain containing
 548 .I C
 549 itself is named
 550 .I H
 551 (though keep in mind that it's possible that
 552 .I H
 553 is in fact
 554 .I C
 555 itself.)
 556 .PP
 557 The
 558 .B ilayout
 559 structure contains one member for each of
 560 .IR C 's
 561 superclass chains.
 562 The first such member is
 563 .IP
 564 .B
 565 .B union
 566 .IB C __ichainu_ h
 567 .IB h ;
 568 .PP
 569 described below;
 570 this is followed by members
 571 .IP
 572 .B union
 573 .IB B __ichainu_ i
 574 .IB i ;
 575 .PP
 576 for each other chain,
 577 where
 578 .I I
 579 is the head
 580 and
 581 .I B
 582 the tail (most-specific) class of the chain.
 583 The members are in decreasing order
 584 of the specificity of the chains' most-specific classes.
 585 (Note that all but the first of these unions
 586 has already been defined as part of
 587 the definition of the corresponding
 588 .IR B .)
 589 .PP
 590 The
 591 .B ichainu
 592 union contains a member for each class in the chain.
 593 The first is
 594 .IP
 595 .B struct
 596 .IB C __ichain_ h
 597 .IB c ;
 598 .PP
 599 and this is followed by corresponding members
 600 .IP
 601 .B struct
 602 .IB A __ichain_ h
 603 .IB a ;
 604 .PP
 605 for each of
 606 .IR C 's
 607 superclasses
 608 .IR A
 609 in the same chain in some (unimportant) order.
 610 The (somewhat obtuse) purpose of this union is to
 611 engage the `common initial sequence' rule of
 612 C99 (clause 6.5.2.3).
 613 .PP
 614 The
 615 .B ichain
 616 structure contains (in order), a pointer
 617 .IP
 618 .B const
 619 .B struct
 620 .IB C __vt_ h
 621 .B *_vt;
 622 .PP
 623 followed by a structure
 624 .IP
 625 .B struct
 626 .IB A __islots
 627 .IB a ;
 628 .PP
 629 for each superclass
 630 .I A
 631 of
 632 .IR C
 633 in the same chain which defines slots,
 634 from least- to most-specific;
 635 if
 636 .I C
 637 defines any slots,
 638 then the last member is
 639 .IP
 640 .B struct
 641 .IB C __islots
 642 .IB c ;
 643 .PP
 644 A `pointer to
 645 .IR C '
 646 is always assumed
 647 (and, indeed, defined in C's type system)
 648 to be a pointer to the
 649 .B struct
 650 .IB C __ichain_ h \fR.
 651 .PP
 652 Finally, the
 653 .B islots
 654 structure simply contains one member for each slot defined by
 655 .I C
 656 in the order they appear in the class definition.
 657 .
 658 .SS Generic vtable structure
 659 As described above,
 660 each
 661 .B ichain
 662 structure of an instance's storage
 663 has a vtable pointer
 664 .IP
 665 .B const
 666 .B struct
 667 .IB C __vt_ h
 668 .B *_vt;
 669 .PP
 670 In general,
 671 the vtables for the different chains
 672 will have
 673 .I different
 674 structures.
 675 .PP
 676 The instance layout splits neatly into disjoint chains.
 677 This is necessary because
 678 each
 679 .B ichain
 680 must have as a prefix the
 681 .B ichain
 682 for each superclass in the same chain,
 683 and each slot must be stored in exactly one place.
 684 The layout of vtables doesn't have this second requirement:
 685 it doesn't matter that there are
 686 multiple method entry pointers
 687 for the same effective method
 688 as long as they all work correctly.
 689 Indeed, it's essential that there are multiple entry pointers,
 690 because each chain's method entry function
 691 will need to apply a different offset to the receiver pointer
 692 before invoking the effective method.
 693 .PP
 694 A vtable for a class
 695 .I C
 696 with chain head
 697 .I H
 698 has the following general structure.
 699 .VS
 700 union \fIC\fB__vtu_\fIh\fB {
 701 \h'2n'struct \fIC\fB__vt_\fIh\fB {
 702 \h'4n'const \fIP\fB *_class;
 703 \h'4n'size_t _base;
 704 \h'4n'\fR...\fB
 705 \h'4n'const \fIQ\fB *_cls_\fIj\fB;
 706 \h'4n'\fR...\fB
 707 \h'4n'ptrdiff_t _off_\fIi\fB;
 708 \h'4n'\fR...\fB
 709 \h'4n'struct \fIC\fB__vtmsgs_\fIa\fB {
 710 \h'6n'\fItype\fB (*\fImsg\fB)(\fIC\fB *, \fR...\fB);
 711 \h'6n'\fR...\fB
 712 \h'4n'} \fIa\fB;
 713 \h'4n'\fR...\fB
 714 \h'2n'} \fIc\fB;
 715 };
 716
 717 extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
 718 .VE
 719 In the following,
 720 let
 721 .I M
 722 be the metaclass of
 723 .IR C .
 724 .PP
 725 The outer layer is a
 726 .B union
 727 .IB C __vtu_ h
 728 containing a member
 729 .IP
 730 .B struct
 731 .IB A __vt_ h
 732 .IB a ;
 733 .PP
 734 for each of
 735 .IR C 's
 736 superclasses
 737 .I A
 738 in the same chain,
 739 with
 740 .I C
 741 itself listed first.
 742 This is mostly an irrelevant detail,
 743 whose purpose is to defend against malicious compilers:
 744 pointers are always to one of the inner
 745 .B vt
 746 structures.
 747 It's important only because it's the outer
 748 .B vtu
 749 union which is exported by name.
 750 Specifically, for each chain of
 751 .IR C 's
 752 superclasses
 753 there is an external object
 754 .IP
 755 .B const union
 756 .IB A __vtu_ i
 757 .IB C __vtable_ i ;
 758 .PP
 759 where
 760 .I A
 761 and
 762 .I I
 763 are respectively the most and least specific classes in the chain.
 764 .PP
 765 The first member in the
 766 .B vt
 767 structure is the
 768 .I root class pointer
 769 .IP
 770 .B const
 771 .IR P
 772 .B *_class;
 773 .PP
 774 Among the superclasses of
 775 .I C
 776 there must be exactly one class
 777 .I O
 778 which itself has no direct superclasses;
 779 this is the
 780 .I root superclass
 781 of
 782 .IR C .
 783 (This is a rule enforced by the Sod translator.)
 784 The metaclass
 785 .I R
 786 of
 787 .I O
 788 is then the
 789 .I root metaclass
 790 of
 791 .IR C .
 792 The
 793 .B _class
 794 member points to the
 795 .B ichain
 796 structure of most specific superclass
 797 .I P
 798 of
 799 .I M
 800 in the same chain as
 801 .IR R .
 802 .PP
 803 This is followed by the
 804 .I base offset
 805 .IP
 806 .B size_t
 807 .B _base;
 808 .PP
 809 which is simply the offset of the
 810 .B ichain
 811 structure from the instance base.
 812 .PP
 813 The rest of the vtable structure is populated
 814 by walking the superclass chain containing
 815 .I C
 816 as follows.
 817 For each such superclass
 818 .IR B ,
 819 in increasing order of specificity,
 820 walk the class precedence list of
 821 .IR B ,
 822 again starting with its least-specific superclass.
 823 (This complex procedure guarantees that
 824 the vtable structure for a class is a prefix of
 825 the vtable structure for any of its subclasses in the same chain.)
 826 .PP
 827 So, let
 828 .I A
 829 be some superclass of
 830 .I C
 831 which has been encountered during this traversal.
 832 .hP \*o
 833 Let
 834 .I N
 835 be the metaclass of
 836 .IR A .
 837 Examine the superclass chains of
 838 .I N
 839 in order of decreasing specificity of their most-specific classes.
 840 Let
 841 .I J
 842 be the chain head of such a chain,
 843 and let
 844 .I Q
 845 be the most specific superclass of
 846 .I M
 847 in the same chain as
 848 .IR J .
 849 If there is currently no class pointer
 850 for the chain headed by
 851 .IR J ,
 852 then add a member
 853 .RS
 854 .IP
 855 .B const
 856 .I Q
 857 .BI *_cls_ j ;
 858 .PP
 859 to the vtable
 860 pointing to the appropriate
 861 .B islots
 862 structure within
 863 .IR M 's
 864 class object,
 865 where
 866 .I Q
 867 is the most specific superclass of
 868 .I M
 869 in the same chain as
 870 .IR J .
 871 .RE
 872 .hP \*o
 873 Examine the superclass chains of
 874 .I A
 875 in order of decreasing specificity of their most-specific classes.
 876 Let
 877 .I I
 878 be the chain head of such a chain.
 879 If there is currently no member
 880 .BI _off_ i
 881 then add a member
 882 .RS
 883 .IP
 884 .B ptrdiff_t
 885 .BI _off_ i ;
 886 .PP
 887 to the vtable,
 888 containing the (signed) offset from the
 889 .B ichain
 890 structure of the chain headed by
 891 .I h
 892 to that of the chain headed by
 893 .I i
 894 within the instance's layout.
 895 .RE
 896 .hP \*o
 897 If class
 898 .I A
 899 defines any messages,
 900 and there is currently no member
 901 .IR a ,
 902 then add a member
 903 .RS
 904 .IP
 905 .B struct
 906 .IB C __vtmsgs_ a
 907 .IB a ;
 908 .PP
 909 to the vtable.
 910 See below.
 911 .RE
 912 .PP
 913 Finally, the
 914 .B vtmsgs
 915 structures contain pointers to the effective method entry functions
 916 for the messages defined by a superclass.
 917 There may be more than one method entry for a message,
 918 but all of the entry pointers for a message appear together,
 919 and entry pointers for separate messages appear
 920 in the order in which the messages are defined.
 921 If the receiver class has no applicable primary method for a message
 922 then it's usual for the method entry pointer to be null
 923 (though, as with a lot of things in Sod,
 924 extensions may do something different).
 925 .PP
 926 For a standard message which takes a fixed number of arguments,
 927 defined as
 928 .IP
 929 .I tr
 930 .IB m ( \c
 931 .I t1
 932 .IB a1 ,
 933 .RB ... ,
 934 .I tn
 935 .IB an );
 936 .PP
 937 there is always a `main' entry point,
 938 .IP
 939 .I tr
 940 .BI (* m )( \c
 941 .I C
 942 .BI * me ,
 943 .I t1
 944 .IB a1 ,
 945 .RB ... ,
 946 .I tn
 947 .IB an );
 948 .PP
 949 For a standard message which takes a variable number of arguments,
 950 defined as
 951 .IP
 952 .I tr
 953 .IB m ( \c
 954 .I t1
 955 .IB a1 ,
 956 .RB ... ,
 957 .I tn
 958 .IB an ,
 959 .B ...);
 960 .PP
 961 or a standard message which takes keyword arguments,
 962 defined as
 963 .IP
 964 .I tr
 965 .IB m ( \c
 966 .I t1
 967 .IB a1 ,
 968 .RB ... ,
 969 .I tn
 970 .IB an ?\&
 971 .IR tn +1
 972 .IR kn +1
 973 .RB [ =
 974 .IR dn +1] \c
 975 .B ,
 976 .I tm
 977 .I km
 978 .RB [ =
 979 .IR dm ] \c
 980 );
 981 .PP
 982 two entry points are defined:
 983 the usual `main' entry point
 984 which accepts a variable number of
 985 arguments,
 986 and a `valist' entry point
 987 which accepts an argument of type
 988 .B va_list
 989 in place of the variable portion of the argument list
 990 or keywords.
 991 .IP
 992 .I tr
 993 .BI (* m )( \c
 994 .I C
 995 .BI * me ,
 996 .I t1
 997 .IB a1 ,
 998 .RB ... ,
 999 .I tn
1000 .IB an ,
1001 .B ...);
1002 .br
1003 .I tr
1004 .BI (* m __v)( \c
1005 .I C
1006 .BI * me ,
1007 .I t1
1008 .IB a1 ,
1009 .RB ... ,
1010 .I tn
1011 .IB an ,
1012 .B va_list
1013 .IB sod__ap );
1014 .
1015 .SS Additional definitions
1016 In addition to the instance and vtable structures described above,
1017 the following definitions are made for each class
1018 .IR C .
1019 .PP
1020 For each message
1021 .I m
1022 directly defined by
1023 .I C
1024 there is a macro definition
1025 .IP
1026 .B #define
1027 .IB C _ m ( me ,
1028 .RB ... )
1029 .IB me ->_vt-> c . m ( me ,
1030 .RB ... )
1031 .PP
1032 which makes sending the message
1033 .I m
1034 to an instance of (any subclass of)
1035 .I C
1036 somewhat less ugly.
1037 If
1038 .I m
1039 takes a variable number of arguments,
1040 or keyword arguments,
1041 the macro is more complicated
1042 and is only available in compilers advertising C99 support,
1043 but the effect is the same.
1044 For each variable-argument message,
1045 there is also an additional macro
1046 for calling the `valist' entry point.
1047 .IP
1048 .B #define
1049 .IB C _ m __v( me ,
1050 .RB ...,
1051 .IB sod__ap )
1052 .if !t \{\
1053 \e
1054 .br
1055 \h'4m'\c
1056 .\}
1057 .IB me ->_vt-> c . m __v( me ,
1058 .RB ...,
1059 .IB sod__ap )
1060 .PP
1061 For each proper superclass
1062 .I A
1063 of
1064 .IR C ,
1065 there is a macro defined
1066 .IP
1067 .I A
1068 .BI * C __CONV_ a ( C
1069 .BI * _obj );
1070 .PP
1071 (named in
1072 .IR "upper case" )
1073 which converts a (static-type) pointer to
1074 .I C
1075 to a pointer to the same actual instance,
1076 but statically typed as a pointer to
1077 .IR A .
1078 This is most useful when
1079 .I A
1080 is not in the same chain as
1081 .I C
1082 since in-chain upcasts are both trivial and rarely needed,
1083 but the full set is defined for the sake of completeness.
1084 .PP
1085 Finally, the class object is defined as
1086 .IP
1087 .B extern const struct
1088 .IB R __ilayout
1089 .IB C __classobj;
1090 .br
1091 .B #define
1092 .IB C __class
1093 .BI (& C __classobj. j . r )
1094 .br
1095 .B #define
1096 .IB C __cls_ k
1097 .BI (& C __classobj. k . n )
1098 .br
1099 \&...
1100 .PP
1101 The exported symbol
1102 .IB C __classobj
1103 contains the entire class instance.
1104 This is usually rather unwieldy.
1105 The macro
1106 .IB C __class
1107 is usable as a pointer of type
1108 .B const
1109 .I R
1110 .BR * ,
1111 where
1112 .I R
1113 is the root metaclass of
1114 .IR C ,
1115 i.e., the metaclass of the least specific superclass of
1116 .IR C ;
1117 usually this is
1118 .BR "const SodClass\ *" .
1119 For each chain of
1120 .IR C 's
1121 metaclass, a macro
1122 .IB C __cls_ k
1123 is defined, usable as a pointer of type
1124 .B const
1125 .IR N \ \c
1126 .BR * ,
1127 where
1128 .I K
1129 and
1130 .I N
1131 are the chain's head and tail classes
1132 (i.e., the least- and most-specific classes in the chain)
1133 respectively;
1134 this macro is
1135 .I omitted
1136 if
1137 .IR N "\ =\ " R ,
1138 i.e., in the common case where
1139 .IR C 's
1140 metaclass is precisely the root metaclass,
1141 since the existing
1142 .IB C __class
1143 macro is already sufficient.
1144 .
1145 .\"--------------------------------------------------------------------------
1146 .SH SEE ALSO
1147 .BR sod (3).
1148 .
1149 .\"--------------------------------------------------------------------------
1150 .SH AUTHOR
1151 Mark Wooding, <mdw@distorted.org.uk>
1152 .
1153 .\"----- That's all, folks --------------------------------------------------