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