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 .IP
 516 .nf
 517 .ft B
 518 struct \fIC\fB__ilayout {
 519 \h'2n'union \fIC\fB__ichainu_\fIh\fB {
 520 \h'4n'struct \fIC\fB__ichain_\fIh\fB {
 521 \h'6n'const struct \fIC\fB__vt_\fIh\fB *_vt;
 522 \h'6n'struct \fIH\fB__islots \fIh\fB;
 523 \h'6n'\fR...\fB
 524 \h'6n'struct \fIC\fB__islots {
 525 \h'8n'\fItype\fB \fIslota\fB;
 526 \h'8n'\fR...\fB
 527 \h'6n'} \fIc\fB;
 528 \h'4n'} \fIc\fB;
 529 \h'4n'\fR...\fB
 530 \h'4n'struct \fIA\fB__ichain_\fIh\fB \fIa\fB;
 531 \h'2n'} \fIh\fB;
 532 \h'2n'union \fIB\fB__ichainu_\fIi\fB \fIi\fB;
 533 \h'2n'\fR...\fB
 534 };
 535
 536 typedef struct \fIC\fB__ichain_\fIh\fB \fIC\fB;
 537 .ft P
 538 .fi
 539 .PP
 540 The set of superclasses of
 541 .IR C ,
 542 including itself,
 543 can be partitioned into chains
 544 by following their distinguished superclass links.
 545 (Formally, the chains are the equivalence classes determined by
 546 the reflexive, symmetric, transitive closure of
 547 the `links to' relation.)
 548 Chains are identified by naming their least specific classes;
 549 the least specific class in a chain is called the
 550 .IR "chain head" .
 551 Suppose that the chain head of the chain containing
 552 .I C
 553 itself is named
 554 .I H
 555 (though keep in mind that it's possible that
 556 .I H
 557 is in fact
 558 .I C
 559 itself.)
 560 .PP
 561 The
 562 .B ilayout
 563 structure contains one member for each of
 564 .IR C 's
 565 superclass chains.
 566 The first such member is
 567 .IP
 568 .B
 569 .B union
 570 .IB C __ichainu_ h
 571 .IB h ;
 572 .PP
 573 described below;
 574 this is followed by members
 575 .IP
 576 .B union
 577 .IB B __ichainu_ i
 578 .IB i ;
 579 .PP
 580 for each other chain,
 581 where
 582 .I I
 583 is the head
 584 and
 585 .I B
 586 the tail (most-specific) class of the chain.
 587 The members are in decreasing order
 588 of the specificity of the chains' most-specific classes.
 589 (Note that all but the first of these unions
 590 has already been defined as part of
 591 the definition of the corresponding
 592 .IR B .)
 593 .PP
 594 The
 595 .B ichainu
 596 union contains a member for each class in the chain.
 597 The first is
 598 .IP
 599 .B struct
 600 .IB C __ichain_ h
 601 .IB c ;
 602 .PP
 603 and this is followed by corresponding members
 604 .IP
 605 .B struct
 606 .IB A __ichain_ h
 607 .IB a ;
 608 .PP
 609 for each of
 610 .IR C 's
 611 superclasses
 612 .IR A
 613 in the same chain in some (unimportant) order.
 614 The (somewhat obtuse) purpose of this union is to
 615 engage the `common initial sequence' rule of
 616 C99 (clause 6.5.2.3).
 617 .PP
 618 The
 619 .B ichain
 620 structure contains (in order), a pointer
 621 .IP
 622 .B const
 623 .B struct
 624 .IB C __vt_ h
 625 .B *_vt;
 626 .PP
 627 followed by a structure
 628 .IP
 629 .B struct
 630 .IB A __islots
 631 .IB a ;
 632 .PP
 633 for each superclass
 634 .I A
 635 of
 636 .IR C
 637 in the same chain which defines slots,
 638 from least- to most-specific;
 639 if
 640 .I C
 641 defines any slots,
 642 then the last member is
 643 .IP
 644 .B struct
 645 .IB C __islots
 646 .IB c ;
 647 .PP
 648 A `pointer to
 649 .IR C '
 650 is always assumed
 651 (and, indeed, defined in C's type system)
 652 to be a pointer to the
 653 .B struct
 654 .IB C __ichain_ h \fR.
 655 .PP
 656 Finally, the
 657 .B islots
 658 structure simply contains one member for each slot defined by
 659 .I C
 660 in the order they appear in the class definition.
 661 .
 662 .SS Generic vtable structure
 663 As described above,
 664 each
 665 .B ichain
 666 structure of an instance's storage
 667 has a vtable pointer
 668 .IP
 669 .B const
 670 .B struct
 671 .IB C __vt_ h
 672 .B *_vt;
 673 .PP
 674 In general,
 675 the vtables for the different chains
 676 will have
 677 .I different
 678 structures.
 679 .PP
 680 The instance layout splits neatly into disjoint chains.
 681 This is necessary because
 682 each
 683 .B ichain
 684 must have as a prefix the
 685 .B ichain
 686 for each superclass in the same chain,
 687 and each slot must be stored in exactly one place.
 688 The layout of vtables doesn't have this second requirement:
 689 it doesn't matter that there are
 690 multiple method entry pointers
 691 for the same effective method
 692 as long as they all work correctly.
 693 Indeed, it's essential that there are multiple entry pointers,
 694 because each chain's method entry function
 695 will need to apply a different offset to the receiver pointer
 696 before invoking the effective method.
 697 .PP
 698 A vtable for a class
 699 .I C
 700 with chain head
 701 .I H
 702 has the following general structure.
 703 .IP
 704 .nf
 705 .ft B
 706 union \fIC\fB__vtu_\fIh\fB {
 707 \h'2n'struct \fIC\fB__vt_\fIh\fB {
 708 \h'4n'const \fIP\fB *_class;
 709 \h'4n'size_t _base;
 710 \h'4n'\fR...\fB
 711 \h'4n'const \fIQ\fB *_cls_\fIj\fB;
 712 \h'4n'\fR...\fB
 713 \h'4n'ptrdiff_t _off_\fIi\fB;
 714 \h'4n'\fR...\fB
 715 \h'4n'struct \fIC\fB__vtmsgs_\fIa\fB {
 716 \h'6n'\fItype\fB (*\fImsg\fB)(\fIC\fB *, \fR...\fB);
 717 \h'6n'\fR...\fB
 718 \h'4n'} \fIa\fB;
 719 \h'4n'\fR...\fB
 720 \h'2n'} \fIc\fB;
 721 };
 722
 723 extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
 724 .ft P
 725 .fi
 726 .PP
 727 In the following,
 728 let
 729 .I M
 730 be the metaclass of
 731 .IR C .
 732 .PP
 733 The outer layer is a
 734 .B union
 735 .IB C __vtu_ h
 736 containing a member
 737 .IP
 738 .B struct
 739 .IB A __vt_ h
 740 .IB a ;
 741 .PP
 742 for each of
 743 .IR C 's
 744 superclasses
 745 .I A
 746 in the same chain,
 747 with
 748 .I C
 749 itself listed first.
 750 This is mostly an irrelevant detail,
 751 whose purpose is to defend against malicious compilers:
 752 pointers are always to one of the inner
 753 .B vt
 754 structures.
 755 It's important only because it's the outer
 756 .B vtu
 757 union which is exported by name.
 758 Specifically, for each chain of
 759 .IR C 's
 760 superclasses
 761 there is an external object
 762 .IP
 763 .B const union
 764 .IB A __vtu_ i
 765 .IB C __vtable_ i ;
 766 .PP
 767 where
 768 .I A
 769 and
 770 .I I
 771 are respectively the most and least specific classes in the chain.
 772 .PP
 773 The first member in the
 774 .B vt
 775 structure is the
 776 .I root class pointer
 777 .IP
 778 .B const
 779 .IR P
 780 .B *_class;
 781 .PP
 782 Among the superclasses of
 783 .I C
 784 there must be exactly one class
 785 .I O
 786 which itself has no direct superclasses;
 787 this is the
 788 .I root superclass
 789 of
 790 .IR C .
 791 (This is a rule enforced by the Sod translator.)
 792 The metaclass
 793 .I R
 794 of
 795 .I O
 796 is then the
 797 .I root metaclass
 798 of
 799 .IR C .
 800 The
 801 .B _class
 802 member points to the
 803 .B ichain
 804 structure of most specific superclass
 805 .I P
 806 of
 807 .I M
 808 in the same chain as
 809 .IR R .
 810 .PP
 811 This is followed by the
 812 .I base offset
 813 .IP
 814 .B size_t
 815 .B _base;
 816 .PP
 817 which is simply the offset of the
 818 .B ichain
 819 structure from the instance base.
 820 .PP
 821 The rest of the vtable structure is populated
 822 by walking the superclass chain containing
 823 .I C
 824 as follows.
 825 For each such superclass
 826 .IR B ,
 827 in increasing order of specificity,
 828 walk the class precedence list of
 829 .IR B ,
 830 again starting with its least-specific superclass.
 831 (This complex procedure guarantees that
 832 the vtable structure for a class is a prefix of
 833 the vtable structure for any of its subclasses in the same chain.)
 834 .PP
 835 So, let
 836 .I A
 837 be some superclass of
 838 .I C
 839 which has been encountered during this traversal.
 840 .hP \*o
 841 Let
 842 .I N
 843 be the metaclass of
 844 .IR A .
 845 Examine the superclass chains of
 846 .I N
 847 in order of decreasing specificity of their most-specific classes.
 848 Let
 849 .I J
 850 be the chain head of such a chain,
 851 and let
 852 .I Q
 853 be the most specific superclass of
 854 .I M
 855 in the same chain as
 856 .IR J .
 857 If there is currently no class pointer
 858 for the chain headed by
 859 .IR J ,
 860 then add a member
 861 .RS
 862 .IP
 863 .B const
 864 .I Q
 865 .BI *_cls_ j ;
 866 .PP
 867 to the vtable
 868 pointing to the appropriate
 869 .B islots
 870 structure within
 871 .IR M 's
 872 class object,
 873 where
 874 .I Q
 875 is the most specific superclass of
 876 .I M
 877 in the same chain as
 878 .IR J .
 879 .RE
 880 .hP \*o
 881 Examine the superclass chains of
 882 .I A
 883 in order of decreasing specificity of their most-specific classes.
 884 Let
 885 .I I
 886 be the chain head of such a chain.
 887 If there is currently no member
 888 .BI _off_ i
 889 then add a member
 890 .RS
 891 .IP
 892 .B ptrdiff_t
 893 .BI _off_ i ;
 894 .PP
 895 to the vtable,
 896 containing the (signed) offset from the
 897 .B ichain
 898 structure of the chain headed by
 899 .I h
 900 to that of the chain headed by
 901 .I i
 902 within the instance's layout.
 903 .RE
 904 .hP \*o
 905 If class
 906 .I A
 907 defines any messages,
 908 and there is currently no member
 909 .IR a ,
 910 then add a member
 911 .RS
 912 .IP
 913 .B struct
 914 .IB C __vtmsgs_ a
 915 .IB a ;
 916 .PP
 917 to the vtable.
 918 See below.
 919 .RE
 920 .PP
 921 Finally, the
 922 .B vtmsgs
 923 structures contain pointers to the effective method entry functions
 924 for the messages defined by a superclass.
 925 There may be more than one method entry for a message,
 926 but all of the entry pointers for a message appear together,
 927 and entry pointers for separate messages appear
 928 in the order in which the messages are defined.
 929 If the receiver class has no applicable primary method for a message
 930 then it's usual for the method entry pointer to be null
 931 (though, as with a lot of things in Sod,
 932 extensions may do something different).
 933 .PP
 934 For a standard message which takes a fixed number of arguments,
 935 defined as
 936 .IP
 937 .I tr
 938 .IB m ( \c
 939 .I t1
 940 .IB a1 ,
 941 .RB ... ,
 942 .I tn
 943 .IB an );
 944 .PP
 945 there is always a `main' entry point,
 946 .IP
 947 .I tr
 948 .BI (* m )( \c
 949 .I C
 950 .BI * me ,
 951 .I t1
 952 .IB a1 ,
 953 .RB ... ,
 954 .I tn
 955 .IB an );
 956 .PP
 957 For a standard message which takes a variable number of arguments,
 958 defined as
 959 .IP
 960 .I tr
 961 .IB m ( \c
 962 .I t1
 963 .IB a1 ,
 964 .RB ... ,
 965 .I tn
 966 .IB an ,
 967 .B ...);
 968 .PP
 969 or a standard message which takes keyword arguments,
 970 defined as
 971 .IP
 972 .I tr
 973 .IB m ( \c
 974 .I t1
 975 .IB a1 ,
 976 .RB ... ,
 977 .I tn
 978 .IB an ?\&
 979 .IR tn +1
 980 .IR kn +1
 981 .RB [ =
 982 .IR dn +1] \c
 983 .B ,
 984 .I tm
 985 .I km
 986 .RB [ =
 987 .IR dm ] \c
 988 );
 989 .PP
 990 two entry points are defined:
 991 the usual `main' entry point
 992 which accepts a variable number of
 993 arguments,
 994 and a `valist' entry point
 995 which accepts an argument of type
 996 .B va_list
 997 in place of the variable portion of the argument list
 998 or keywords.
 999 .IP
1000 .I tr
1001 .BI (* m )( \c
1002 .I C
1003 .BI * me ,
1004 .I t1
1005 .IB a1 ,
1006 .RB ... ,
1007 .I tn
1008 .IB an ,
1009 .B ...);
1010 .br
1011 .I tr
1012 .BI (* m __v)( \c
1013 .I C
1014 .BI * me ,
1015 .I t1
1016 .IB a1 ,
1017 .RB ... ,
1018 .I tn
1019 .IB an ,
1020 .B va_list
1021 .IB sod__ap );
1022 .
1023 .SS Additional definitions
1024 In addition to the instance and vtable structures described above,
1025 the following definitions are made for each class
1026 .IR C .
1027 .PP
1028 For each message
1029 .I m
1030 directly defined by
1031 .I C
1032 there is a macro definition
1033 .IP
1034 .B #define
1035 .IB C _ m ( me ,
1036 .RB ... )
1037 .IB me ->_vt-> c . m ( me ,
1038 .RB ... )
1039 .PP
1040 which makes sending the message
1041 .I m
1042 to an instance of (any subclass of)
1043 .I C
1044 somewhat less ugly.
1045 If
1046 .I m
1047 takes a variable number of arguments,
1048 or keyword arguments,
1049 the macro is more complicated
1050 and is only available in compilers advertising C99 support,
1051 but the effect is the same.
1052 For each variable-argument message,
1053 there is also an additional macro
1054 for calling the `valist' entry point.
1055 .IP
1056 .B #define
1057 .IB C _ m __v( me ,
1058 .RB ...,
1059 .IB sod__ap )
1060 .if !t \{\
1061 \e
1062 .br
1063 \h'4m'\c
1064 .\}
1065 .IB me ->_vt-> c . m __v( me ,
1066 .RB ...,
1067 .IB sod__ap )
1068 .PP
1069 For each proper superclass
1070 .I A
1071 of
1072 .IR C ,
1073 there is a macro defined
1074 .IP
1075 .I A
1076 .BI * C __CONV_ a ( C
1077 .BI * _obj );
1078 .PP
1079 (named in
1080 .IR "upper case" )
1081 which converts a (static-type) pointer to
1082 .I C
1083 to a pointer to the same actual instance,
1084 but statically typed as a pointer to
1085 .IR A .
1086 This is most useful when
1087 .I A
1088 is not in the same chain as
1089 .I C
1090 since in-chain upcasts are both trivial and rarely needed,
1091 but the full set is defined for the sake of completeness.
1092 .PP
1093 Finally, the class object is defined as
1094 .IP
1095 .B extern const struct
1096 .IB R __ilayout
1097 .IB C __classobj;
1098 .br
1099 .B #define
1100 .IB C __class
1101 .BI (& C __classobj. j . r )
1102 .br
1103 .B #define
1104 .IB C __cls_ k
1105 .BI (& C __classobj. k . n )
1106 .br
1107 \&...
1108 .PP
1109 The exported symbol
1110 .IB C __classobj
1111 contains the entire class instance.
1112 This is usually rather unwieldy.
1113 The macro
1114 .IB C __class
1115 is usable as a pointer of type
1116 .B const
1117 .I R
1118 .BR * ,
1119 where
1120 .I R
1121 is the root metaclass of
1122 .IR C ,
1123 i.e., the metaclass of the least specific superclass of
1124 .IR C ;
1125 usually this is
1126 .BR "const SodClass\ *" .
1127 For each chain of
1128 .IR C 's
1129 metaclass, a macro
1130 .IB C __cls_ k
1131 is defined, usable as a pointer of type
1132 .B const
1133 .IR N \ \c
1134 .BR * ,
1135 where
1136 .I K
1137 and
1138 .I N
1139 are the chain's head and tail classes
1140 (i.e., the least- and most-specific classes in the chain)
1141 respectively;
1142 this macro is
1143 .I omitted
1144 if
1145 .IR N "\ =\ " R ,
1146 i.e., in the common case where
1147 .IR C 's
1148 metaclass is precisely the root metaclass,
1149 since the existing
1150 .IB C __class
1151 macro is already sufficient.
1152 .
1153 .\"--------------------------------------------------------------------------
1154 .SH SEE ALSO
1155 .BR sod (3).
1156 .
1157 .\"--------------------------------------------------------------------------
1158 .SH AUTHOR
1159 Mark Wooding, <mdw@distorted.org.uk>
1160 .
1161 .\"----- That's all, folks --------------------------------------------------