3 .\" Description of the main Sod data structures
5 .\" (c) 2015 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the Sensible 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 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.
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.
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.
27 .\" Highlight using terminal escapes, rather than overstriking.
30 .\" String definitions and font selection.
39 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
42 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
45 .\"--------------------------------------------------------------------------
46 .TH sod-structs 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
49 sod-structs \- main Sod data structures
51 .\"--------------------------------------------------------------------------
57 typedef struct SodObject__ichain_obj SodObject;
58 typedef struct SodClass__ichain_obj SodClass;
61 \h'2n'const struct sod_vtable *_vt;
65 \h'2n'const SodClass *_class;
69 struct SodObject__vt_obj {
70 \h'2n'const SodClass *_class;
74 struct SodObject__ilayout {
76 \h'4n'struct SodObject__ichain_obj {
77 \h'6n'const struct SodObject__vt_obj *_vt;
82 extern const struct SodClass__ilayout SodObject__classobj;
83 #define SodObject__class (&SodObject__classobj.obj.cls)
85 struct SodClass__vt_obj {
86 \h'2n'const SodClass *_class;
90 struct SodObject__ilayout {
92 \h'4n'struct SodClass__ichain_obj {
93 \h'6n'const struct SodClass__vt_obj *_vt;
94 \h'6n'struct SodClass__islots {
95 \h'8n'const char *name;
96 \h'8n'const char *nick;
98 \h'8n'void *(*imprint)(void *\fIp\fB);
99 \h'8n'void *(*init)(void *\fIp\fB);
100 \h'8n'size_t n_supers;
101 \h'8n'const SodClass *const *supers;
103 \h'8n'const SodClass *const *cpl;
104 \h'8n'const SodClass *link;
105 \h'8n'const SodClass *head;
107 \h'8n'size_t n_chains;
108 \h'8n'const struct sod_chain *chains;
109 \h'8n'size_t off_islots;
110 \h'8n'size_t islotsz;
118 \h'2n'size_t n_classes;
119 \h'2n'const SodClass *const *classes;
120 \h'2n'size_t off_ichain;
121 \h'2n'const struct sod_vtable *vt;
122 \h'2n'size_t ichainsz;
125 extern const struct SodClass__ilayout SodClass__classobj;
126 #define SodClass__class (&SodClass__classobj.obj.cls)
130 .\"--------------------------------------------------------------------------
133 This page describes the structure and layout
134 of standard Sod objects, classes and associated metadata.
135 Note that Sod's object system is very flexible
136 and it's possible for an extension
137 to define a new root class
138 which works very differently from the standard
142 .\"--------------------------------------------------------------------------
143 .SH COMMON INSTANCE STRUCTURE
146 a pointer to an instance actually points to an
148 structure within the instances overall layout structure.
150 Instance chains contain slots and vtable pointers,
152 All instances have the basic structure of a
153 .BR "struct sod_instance" ,
154 which has the following members.
156 .B "const struct sod_vtable *_vt"
159 which has the basic structure of a
160 .BR "struct sod_vtable" ,
163 A vtable contains static metadata needed
164 for efficient conversions and
166 and pointers to the instance's class.
167 Each chain points to a different vtable
168 All vtables have the basic structure of a
169 .BR "struct sod_vtable" ,
170 which has the following members.
172 .B "const SodClass *_class"
173 A pointer to the instance's class object.
176 The offset of this chain structure
177 above the start of the overall instance layout, in bytes.
180 from the instance chain pointer
181 finds the layout base address.
183 .\"--------------------------------------------------------------------------
184 .SH BUILT-IN ROOT OBJECTS
186 This section describes the built-in classes
190 which are the standard roots of the inheritance and metaclass graphs
194 has no direct superclasses,
197 is its own metaclass.
198 It is not possible to define root classes in module files
199 because of circularities:
208 Extensions can define additional root classes,
210 and not really to be recommended.
212 .SS The SodObject class
215 class defines no slots or messages.
218 has no direct superclasses,
219 there is only one chain,
220 and no inherited slots or messages,
221 so the single chain contains only a vtable pointer.
223 Since there are no messages,
226 also has only one chain,
227 the vtable contains only the standard class pointer and offset-to-base
229 In an actual instance of
231 (why would you want one?)
232 the class pointer contains the address of
234 and the offset is zero.
236 .SS The SodClass class
239 class defines no messages,
240 but there are a number of slots.
241 Its only direct superclass is
243 and so (like its superclass) its vtable is trivial.
245 The slots defined are as follows.
248 A pointer to the class's name.
251 A pointer to the class's nickname.
254 The size in bytes required to store an instance of the class.
256 .BI "void *(*imprint)(void *" p );
257 A pointer to a function:
262 bytes of appropriately aligned memory,
263 `imprint' this memory it so that it becomes a minimally functional
264 instance of the class:
265 all of the vtable and class pointers are properly initialized,
266 but the slots are left untouched.
267 The function returns its argument
270 .BI "void *(*init)(void *" p );
271 A pointer to a function:
276 bytes of appropriately aligned memory,
277 initialize an instance of the class in it:
278 all of the vtable and class pointers are initialized,
279 as are slots for which initializers are defined.
280 Other slots are left untouched.
281 The function returns its argument
285 The number of direct superclasses.
286 (This is zero exactly in the case of
289 .B const SodClass *const *supers;
290 A pointer to an array of
292 pointers to class objects
293 listing the class's direct superclasses,
294 in the order in which they were listed in the class definition.
298 then this pointer is null.
301 The number of superclasses in the class's class precedence list.
303 .B const SodClass *const *cpl;
304 A pointer to an array of pointers to class objects
305 listing all of the class's superclasses,
306 from most- to least-specific,
307 starting with the class itself,
312 for all class objects
315 .B const SodClass *link;
316 If the class is a chain head, then this is a null pointer;
317 otherwise it points to the class's distinguished link superclass
318 (which might or might not be a direct superclass).
320 .B const SodClass *head;
321 A pointer to the least-specific class in this class's chain;
323 .IB c ->cls.head->cls.link
335 .IB c ->cls.link->cls.head \fR.
338 The number of less specific superclasses in this class's chain.
347 .IB c ->cls.link->cls.level
351 The number of chains formed by the class's superclasses.
353 .B const struct sod_chain *chains;
354 A pointer to an array of
356 structures (see below) describing the class's superclass chains,
357 in decreasing order of specificity of their most specific classes.
358 It is always the case that
359 .IB c ->cls.chains[0].classes[ c ->cls.level]
363 .B size_t off_islots;
364 The offset of the class's
366 structure relative to its containing
369 The class doesn't define any slots if and only if this is zero.
370 (The offset can't be zero because the vtable pointer is at offset zero.)
373 The size required to store the class's direct slots,
374 i.e., the size of its
377 The class doesn't define any slots if and only if this is zero.
381 structure describes an individual chain of superclasses.
382 It has the following members.
385 The number of classes in the chain.
386 This is always at least one.
388 .B const SodClass *const *classes;
389 A pointer to an array of class pointers
390 listing the classes in the chain from least- to most-specific.
392 .IB classes [ i ]->cls.head
400 .IB classes [0]->cls.link
403 .IB classes [ i ]->cls.link
405 .IB classes [ "i\fR \- 1" ]
412 .B size_t off_ichain;
415 structure for this chain.
417 .B const struct sod_vtable *vt;
418 The vtable for this chain.
419 (It is possible, therefore, to duplicate the behaviour of the
421 function by walking the chain structure.
424 function is much faster, though.)
429 structure for this chain.
431 .\"--------------------------------------------------------------------------
432 .SH CLASS AND VTABLE LAYOUT
434 The layout algorithms for Sod instances and vtables are nontrivial.
435 They are defined here in full detail,
436 since they're effectively fixed by Sod's ABI compatibility guarantees,
437 so they might as well be documented for the sake of interoperating
440 Unfortunately, the descriptions are rather complicated,
441 and, for the most part not necessary to a working understanding of Sod.
442 The skeleton structure definitions shown should be more than enough
443 for readers attempting to make sense of the generated headers and tables.
445 In the description that follows,
446 uppercase letters vary over class names,
447 while the corresponding lowercase letters indicate the class nicknames.
448 Throughout, we consider a class
450 (therefore with nickname
453 .SS Generic instance structure
454 The entire state of an instance of
456 is contained in a single structure of type
462 struct \fIC\fB__ilayout {
463 \h'2n'union \fIC\fB__ichainu_\fIh\fB {
464 \h'4n'struct \fIC\fB__ichain_\fIh\fB {
465 \h'6n'const struct \fIC\fB__vt_\fIh\fB *_vt;
466 \h'6n'struct \fIH\fB__islots \fIh\fB;
468 \h'6n'struct \fIC\fB__islots {
469 \h'8n'\fItype\fB \fIslota\fB;
474 \h'4n'struct \fIH\fB__ichain_\fIh\fB \fIh\fB;
476 \h'2n'union \fIB\fB__ichainu_\fIi\fB \fIi\fB;
480 typedef struct \fIC\fB__ichain_\fIh\fB \fIC\fB;
484 The set of superclasses of
487 can be partitioned into chains
488 by following their distinguished superclass links.
489 (Formally, the chains are the equivalence classes determined by
490 the reflexive, symmetric, transitive closure of
491 the `links to' relation.)
492 Chains are identified by naming their least specific classes;
493 the least specific class in a chain is called the
495 Suppose that the chain head of the chain containing
499 (though keep in mind that it's possible that
507 structure contains one member for each of
510 The first such member is
518 this is followed by members
524 for each other chain,
530 the tail (most-specific) class of the chain.
531 The members are in decreasing order
532 of the specificity of the chains' most-specific classes.
533 (Note that all but the first of these unions
534 has already been defined as part of
535 the definition of the corresponding
540 union contains a member for each class in the chain.
547 and this is followed by corresponding members
557 in the same chain in some (unimportant) order.
561 (and, indeed, defined in C's type system)
562 to be a pointer to the
564 .IB C __ichain_ h \fR.
568 structure contains (in order), a pointer
575 followed by a structure
585 in the same chain which defines slots,
586 from least- to most-specific;
590 then the last member is
598 structure simply contains one member for each slot defined by
600 in the order they appear in the class definition.
602 .SS Generic vtable structure
606 structure of an instance's storage
615 the vtables for the different chains
620 The instance layout split neatly into disjoint chains.
621 This is necessary because
624 must have as a prefix the
626 for each superclass in the same chain,
627 and each slot must be stored in exactly one place.
628 The layout of vtables doesn't have this second requirement:
629 it doesn't matter that there are
630 multiple method entry pointers
631 for the same effective method
632 as long as they all work correctly.
633 Indeed, it's essential that they do,
634 because each chain's method entry function
635 will need to apply a different offset to the receiver pointer
636 before invoking the effective method.
642 has the following general structure.
646 union \fIC\fB__vtu_\fIh\fB {
647 \h'2n'struct \fIC\fB__vt_\fIh\fB {
648 \h'4n'const \fIP\fB *_class;
651 \h'4n'const \fIQ\fB *_cls_\fIj\fB;
653 \h'4n'ptrdiff_t _off_\fIi\fB;
655 \h'4n'struct \fIC\fB__vtmsgs_\fIa\fB {
656 \h'6n'\fItype\fB (*\fImsg\fB)(\fIC\fB *, \fR...\fB);
663 extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
684 This is mostly an irrelevant detail,
685 whose purpose is to defend against malicious compilers:
686 pointers are always to one of the inner
689 It's important only because it's the outer
691 union which is exported by name.
692 Specifically, for each chain of
695 there is an external object
705 are respectively the most and least specific classes in the chain.
707 The first member in the
710 .I root class pointer
716 Among the superclasses of
718 there must be exactly one class
720 which itself has no direct superclasses;
725 (This is a rule enforced by the Sod translator.)
738 structure of most specific superclass
745 This is followed by the
751 which is simply the offset of the
753 structure from the instance base.
755 The rest of the vtable structure is populated
756 by walking the superclass chain containing
759 For each such superclass
761 in increasing order of specificity,
762 walk the class precedence list of
764 again starting with its least-specific superclass.
765 (This complex procedure guarantees that
766 the vtable structure for a class is a prefix of
767 the vtable structure for any of its subclasses in the same chain.)
771 be some superclass of
773 which has been encountered during this traversal.
779 Examine the superclass chains of
781 in order of decreasing specificity of their most-specific classes.
784 be the chain head of such a chain,
787 be the most specific superclass of
791 Then, if there is currently no class pointer of type
801 pointing to the appropriate
808 Examine the superclass chains of
810 in order of decreasing specificity of their most-specific classes.
813 be the chain head of such a chain.
814 If there is currently no member
823 containing the (signed) offset from the
825 structure of the chain headed by
827 to that of the chain headed by
829 within the instance's layout.
834 defines any messages,
835 and there is currently no member
850 structures contain pointers to the effective method entry functions
851 for the messages defined by a superclass.
852 There may be more than one method entry for a message,
853 but all of the entry pointers for a message appear together,
854 and entry pointers for separate messages appear
855 in the order in which the messages are defined.
856 If the receiver class has no applicable primary method for a message
857 then it's usual for the method entry pointer to be null
858 (though, as with a lot of things in Sod,
859 extensions may do something different).
861 For a standard message which takes a fixed number of arguments,
872 there is always a `main' entry point,
884 For a standard message which takes a variable number of arguments,
896 two entry points are defined:
897 the usual `main' entry point
898 which accepts a variable number of
900 and a `valist' entry point
901 which accepts an argument of type
903 in place of the variable portion of the argument list.
928 .SS Additional definitions
929 In addition to the instance and vtable structures described above,
930 the following definitions are made for each class
937 there is a macro definition
942 .IB me ->_vt-> c . m ( me ,
945 which makes sending the message
947 to an instance of (any subclass of)
952 takes a variable number of arguments,
953 the macro is more complicated
954 and is only available in compilers advertising C99 support,
955 but the effect is the same.
956 For each variable-argument message,
957 there is also an additional macro
958 for calling the `valist' entry point.
969 .IB me ->_vt-> c . m __v( me ,
973 For each proper superclass
977 there is a macro defined
980 .BI * C __CONV_ a ( C
985 which converts a (static-type) pointer to
987 to a pointer to the same actual instance,
988 but statically typed as a pointer to
990 This is most useful when
992 is not in the same chain as
994 since in-chain upcasts are both trivial and rarely needed,
995 but the full set is defined for the sake of completeness.
997 Finally, the class object is defined as
999 .B extern const struct
1005 .BI (& C __classobj. j . r )
1009 contains the entire class instance.
1010 This is usually rather unwieldy.
1013 is usable as a pointer of type
1019 is the root metaclass of
1021 i.e., the metaclass of the least specific superclass of
1024 .BR "const SodClass *" .
1026 .\"--------------------------------------------------------------------------
1030 .\"--------------------------------------------------------------------------
1032 Mark Wooding, <mdw@distorted.org.uk>
1034 .\"----- That's all, folks --------------------------------------------------