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