chiark - git - mdw - sod/blob - lib/sod-structs.3

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