3 .\" Description of the main Sod data structures
5 .\" (c) 2015 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the Sensble Object Design, an object system for C.
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.
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.
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.
27 .\" String definitions and font selection.
36 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
39 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
42 .\"--------------------------------------------------------------------------
43 .TH sod-structs 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
46 sod-structs \- main Sod data structures
48 .\"--------------------------------------------------------------------------
54 typedef struct SodObject__ichain_obj SodObject;
55 typedef struct SodClass__ichain_obj SodClass;
58 \h'2n'const struct sod_vtable *_vt;
62 \h'2n'const SodClass *_class;
66 struct SodObject__vt_obj {
67 \h'2n'const SodClass *_class;
71 struct SodObject__ilayout {
73 \h'4n'struct SodObject__ichain_obj {
74 \h'6n'const struct SodObject__vt_obj *_vt;
79 extern const struct SodClass__ilayout SodObject__classobj;
80 #define SodObject__class (&SodObject__classobj.obj.cls)
82 struct SodClass__vt_obj {
83 \h'2n'const SodClass *_class;
87 struct SodObject__ilayout {
89 \h'4n'struct SodClass__ichain_obj {
90 \h'6n'const struct SodClass__vt_obj *_vt;
91 \h'6n'struct SodClass__islots {
92 \h'8n'const char *name;
93 \h'8n'const char *nick;
95 \h'8n'void *(*imprint)(void *\fIp\fB);
96 \h'8n'void *(*init)(void *\fIp\fB);
97 \h'8n'size_t n_supers;
98 \h'8n'const SodClass *const *supers;
100 \h'8n'const SodClass *const *cpl;
101 \h'8n'const SodClass *link;
102 \h'8n'const SodClass *head;
104 \h'8n'size_t n_chains;
105 \h'8n'const struct sod_chain *chains;
106 \h'8n'size_t off_islots;
107 \h'8n'size_t islotsz;
115 \h'2n'size_t n_classes;
116 \h'2n'const SodClass *const *classes;
117 \h'2n'size_t off_ichain;
118 \h'2n'const struct sod_vtable *vt;
119 \h'2n'size_t ichainsz;
122 extern const struct SodClass__ilayout SodClass__classobj;
123 #define SodClass__class (&SodClass__classobj.obj.cls)
127 .\"--------------------------------------------------------------------------
130 This page describes the structure and layout
131 of standard Sod objects, classes and associated metadata.
132 Note that Sod's object system is very flexible
133 and it's possible for an extension
134 to define a new root class
135 which works very differently from the standard
139 .\"--------------------------------------------------------------------------
140 .SH COMMON INSTANCE STRUCTURE
143 a pointer to an instance actually points to an
145 structure within the instances overall layout structure.
147 Instance chains contain slots and vtable pointers,
149 All instances have the basic structure of a
150 .BR "struct sod_instance" ,
151 which has the following members.
153 .B "const struct sod_vtable *_vt"
156 which has the basic structure of a
157 .BR "struct sod_vtable" ,
160 A vtable contains static metadata needed
161 for efficient conversions and
163 and pointers to the instance's class.
164 Each chain points to a different vtable
165 All vtables have the basic structure of a
166 .BR "struct sod_vtable" ,
167 which has the following members.
169 .B "const SodClass *_class"
170 A pointer to the instance's class object.
173 The offset of this chain structure
174 above the start of the overall instance layout, in bytes.
177 from the instance chain pointer
178 finds the layout base address.
180 .\"--------------------------------------------------------------------------
181 .SH BUILT-IN ROOT OBJECTS
183 This section describes the built-in classes
187 which are the standard roots of the inheritance and metaclass graphs
191 has no direct superclasses,
194 is its own metaclass.
195 It is not possible to define root classes in module files
196 because of circularities:
205 Extensions can define additional root classes,
207 and not really to be recommended.
209 .SS The SodObject class
212 class defines no slots or messages.
215 has no direct superclasses,
216 there is only one chain,
217 and no inherited slots or messages,
218 so the single chain contains only a vtable pointer.
220 Since there are no messages,
223 also has only one chain,
224 the vtable contains only the standard class pointer and offset-to-base
226 In an actual instance of
228 (why would you want one?)
229 the class pointer contains the address of
231 and the offset is zero.
233 .SS The SodClass class
236 class defines no messages,
237 but there are a number of slots.
238 Its only direct superclass is
240 and so (like its superclass) its vtable is trivial.
242 The slots defined are as follows.
245 A pointer to the class's name.
248 A pointer to the class's nickname.
251 The size in bytes required to store an instance of the class.
253 .BI "void *(*imprint)(void *" p );
254 A pointer to a function:
259 bytes of appropriately aligned memory,
260 `imprint' this memory it so that it becomes a minimally functional
261 instance of the class:
262 all of the vtable and class pointers are properly initialized,
263 but the slots are left untouched.
264 The function returns its argument
267 .BI "void *(*init)(void *" p );
268 A pointer to a function:
273 bytes of appropriately aligned memory,
274 initialize an instance of the class in it:
275 all of the vtable and class pointers are initialized,
276 as are slots for which initializers are defined.
277 Other slots are left untouched.
278 The function returns its argument
282 The number of direct superclasses.
283 (This is zero exactly in the case of
286 .B const SodClass *const *supers;
287 A pointer to an array of
289 pointers to class objects
290 listing the class's direct superclasses,
291 in the order in which they were listed in the class definition.
295 then this pointer is null.
298 The number of superclasses in the class's class precedence list.
300 .B const SodClass *const *cpl;
301 A pointer to an array of pointers to class objects
302 listing all of the class's superclasses,
303 from most- to least-specific,
304 starting with the class itself,
309 for all class objects
312 .B const SodClass *link;
313 If the class is a chain head, then this is a null pointer;
314 otherwise it points to the class's distinguished link superclass
315 (which might or might not be a direct superclass).
317 .B const SodClass *head;
318 A pointer to the least-specific class in this class's chain;
320 .IB c ->cls.head->cls.link
332 .IB c ->cls.link->cls.head \fR.
335 The number of less specific superclasses in this class's chain.
344 .IB c ->cls.link->cls.level
348 The number of chains formed by the class's superclasses.
350 .B const struct sod_chain *chains;
351 A pointer to an array of
353 structures (see below) describing the class's superclass chains,
354 in decreasing order of specificity of their most specific classes.
355 It is always the case that
356 .IB c ->cls.chains[0].classes[ c ->cls.level]
360 .B size_t off_islots;
361 The offset of the class's
363 structure relative to its containing
366 The class doesn't define any slots if and only if this is zero.
367 (The offset can't be zero because the vtable pointer is at offset zero.)
370 The size required to store the class's direct slots,
371 i.e., the size of its
374 The class doesn't define any slots if and only if this is zero.
378 structure describes an individual chain of superclasses.
379 It has the following members.
382 The number of classes in the chain.
383 This is always at least one.
385 .B const SodClass *const *classes;
386 A pointer to an array of class pointers
387 listing the classes in the chain from least- to most-specific.
389 .IB classes [ i ]->cls.head
397 .IB classes [0]->cls.link
400 .IB classes [ i ]->cls.link
402 .IB classes [ "i\fR \- 1" ]
409 .B size_t off_ichain;
412 structure for this chain.
414 .B const struct sod_vtable *vt;
415 The vtable for this chain.
416 (It is possible, therefore, to duplicate the behaviour of the
418 function by walking the chain structure.
421 function is much faster, though.)
426 structure for this chain.
428 .\"--------------------------------------------------------------------------
429 .SH CLASS AND VTABLE LAYOUT
431 The layout algorithms for Sod instances and vtables are nontrivial.
432 They are defined here in full detail,
433 since they're effectively fixed by Sod's ABI compatibility guarantees,
434 so they might as well be documented for the sake of interoperating
437 Unfortunately, the descriptions are rather complicated,
438 and, for the most part not necessary to a working understanding of Sod.
439 The skeleton structure definitions shown should be more than enough
440 for readers attempting to make sense of the generated headers and tables.
442 In the description that follows,
443 uppercase letters vary over class names,
444 while the corresponding lowercase letters indicate the class nicknames.
445 Throughout, we consider a class
447 (therefore with nickname
450 .SS Generic instance structure
451 The entire state of an instance of
453 is contained in a single structure of type
459 struct \fIC\fB__ilayout {
460 \h'2n'union \fIC\fB__ichainu_\fIh\fB {
461 \h'4n'struct \fIC\fB__ichain_\fIh\fB {
462 \h'6n'const struct \fIC\fB__vt_\fIh\fB *_vt;
463 \h'6n'struct \fIH\fB__islots \fIh\fB;
465 \h'6n'struct \fIC\fB__islots {
466 \h'8n'\fItype\fB \fIslota\fB;
471 \h'4n'struct \fIH\fB__ichain_\fIh\fB \fIh\fB;
473 \h'2n'union \fIB\fB__ichainu_\fIi\fB \fIi\fB;
477 typedef struct \fIC\fB__ichain_\fIh\fB \fIC\fB;
481 The set of superclasses of
484 can be partitioned into chains
485 by following their distinguished superclass links.
486 (Formally, the chains are the equivalence classes determined by
487 the reflexive, symmetric, transitive closure of
488 the `links to' relation.)
489 Chains are identified by naming their least specific classes;
490 the least specific class in a chain is called the
492 Suppose that the chain head of the chain containing
496 (though keep in mind that it's possible that
504 structure contains one member for each of
507 The first such member is
515 this is followed by members
521 for each other chain,
527 the tail (most-specific) class of the chain.
528 The members are in decreasing order
529 of the specificity of the chains' most-specific classes.
530 (Note that all but the first of these unions
531 has already been defined as part of
532 the definition of the corresponding
537 union contains a member for each class in the chain.
544 and this is followed by corresponding members
554 in the same chain in some (unimportant) order.
558 (and, indeed, defined in C's type system)
559 to be a pointer to the
561 .IB C __ichain_ h \fR.
565 structure contains (in order), a pointer
572 followed by a structure
582 in the same chain which defines slots,
583 from least- to most-specific;
587 then the last member is
595 structure simply contains one member for each slot defined by
597 in the order they appear in the class definition.
599 .SS Generic vtable structure
603 structure of an instance's storage
612 the vtables for the different chains
617 The instance layout split neatly into disjoint chains.
618 This is necessary because
621 must have as a prefix the
623 for each superclass in the same chain,
624 and each slot must be stored in exactly one place.
625 The layout of vtables doesn't have this second requirement:
626 it doesn't matter that there are
627 multiple method entry pointers
628 for the same effective method
629 as long as they all work correctly.
630 Indeed, it's essential that they do,
631 because each chain's method entry function
632 will need to apply a different offset to the receiver pointer
633 before invoking the effective method.
639 has the following general structure.
643 union \fIC\fB__vtu_\fIh\fB {
644 \h'2n'struct \fIC\fB__vt_\fIh\fB {
645 \h'4n'const \fIP\fB *_class;
648 \h'4n'const \fIQ\fB *_cls_\fIj\fB;
650 \h'4n'ptrdiff_t _off_\fIi\fB;
652 \h'4n'struct \fIC\fB__vtmsgs_\fIa\fB {
653 \h'6n'\fItype\fB (*\fImsg\fB)(\fIC\fB *, \fR...\fB);
660 extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
681 This is mostly an irrelevant detail,
682 whose purpose is to defend against malicious compilers:
683 pointers are always to one of the inner
686 It's important only because it's the outer
688 union which is exported by name.
689 Specifically, for each chain of
692 there is an external object
702 are respectively the most and least specific classes in the chain.
704 The first member in the
707 .I root class pointer
713 Among the superclasses of
715 there must be exactly one class
717 which itself has no direct superclasses;
722 (This is a rule enforced by the Sod translator.)
735 structure of most specific superclass
742 This is followed by the
748 which is simply the offset of the
750 structure from the instance base.
752 The rest of the vtable structure is populated
753 by walking the superclass chain containing
756 For each such superclass
758 in increasing order of specificity,
759 walk the class precedence list of
761 again starting with its least-specific superclass.
762 (This complex procedure guarantees that
763 the vtable structure for a class is a prefix of
764 the vtable structure for any of its subclasses in the same chain.)
768 be some superclass of
770 which has been encountered during this traversal.
776 Examine the superclass chains of
778 in order of decreasing specificity of their most-specific classes.
781 be the chain head of such a chain,
784 be the most specific superclass of
788 Then, if there is currently no class pointer of type
798 pointing to the appropriate
805 Examine the superclass chains of
807 in order of decreasing specificity of their most-specific classes.
810 be the chain head of such a chain.
811 If there is currently no member
820 containing the (signed) offset from the
822 structure of the chain headed by
824 to that of the chain headed by
826 within the instance's layout.
831 defines any messages,
832 and there is currently no member
847 structures contain pointers to the effective method entry functions
848 for the messages defined by a superclass.
849 There may be more than one method entry for a message,
850 but all of the entry pointers for a message appear together,
851 and entry pointers for separate messages appear
852 in the order in which the messages are defined.
853 If the receiver class has no applicable primary method for a message
854 then it's usual for the method entry pointer to be null
855 (though, as with a lot of things in Sod,
856 extensions may do something different).
858 For a standard message which takes a fixed number of arguments,
869 there is always a `main' entry point,
881 For a standard message which takes a variable number of arguments,
893 two entry points are defined:
894 the usual `main' entry point
895 which accepts a variable number of
897 and a `valist' entry point
898 which accepts an argument of type
900 in place of the variable portion of the argument list.
925 .SS Additional definitions
926 In addition to the instance and vtable structures described above,
927 the following definitions are made for each class
934 there is a macro definition
939 .IB me ->_vt-> c . m ( me ,
942 which makes sending the message
944 to an instance of (any subclass of)
949 takes a variable number of arguments,
950 the macro is more complicated
951 and is only available in compilers advertising C99 support,
952 but the effect is the same.
953 For each variable-argument message,
954 there is also an additional macro
955 for calling the `valist' entry point.
966 .IB me ->_vt-> c . m __v( me ,
970 For each proper superclass
974 there is a macro defined
977 .BI * C __CONV_ a ( C
982 which converts a (static-type) pointer to
984 to a pointer to the same actual instance,
985 but statically typed as a pointer to
987 This is most useful when
989 is not in the same chain as
991 since in-chain upcasts are both trivial and rarely needed,
992 but the full set is defined for the sake of completeness.
994 Finally, the class object is defined as
996 .B extern const struct
1002 .BI (& C __classobj. j . r )
1006 contains the entire class instance.
1007 This is usually rather unwieldy.
1010 is usable as a pointer of type
1016 is the root metaclass of
1018 i.e., the metaclass of the least specific superclass of
1021 .BR "const SodClass *" .
1023 .\"--------------------------------------------------------------------------
1027 .\"--------------------------------------------------------------------------
1029 Mark Wooding, <mdw@distorted.org.uk>
1031 .\"----- That's all, folks --------------------------------------------------