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