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