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