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