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