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 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.
26 .\" Highlight using terminal escapes, rather than overstriking.
29 .\" String definitions and font selection.
38 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
41 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
44 .\"--------------------------------------------------------------------------
45 .TH sod-structs 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
48 sod-structs \- main Sod data structures
50 .\"--------------------------------------------------------------------------
56 typedef struct SodObject__ichain_obj SodObject;
57 typedef struct SodClass__ichain_obj SodClass;
60 \h'2n'const struct sod_vtable *_vt;
64 \h'2n'const SodClass *_class;
68 struct SodObject__vt_obj {
69 \h'2n'const SodClass *_class;
73 struct SodObject__ilayout {
75 \h'4n'struct SodObject__ichain_obj {
76 \h'6n'const struct SodObject__vt_obj *_vt;
81 extern const struct SodClass__ilayout SodObject__classobj;
82 #define SodObject__class (&SodObject__classobj.obj.cls)
84 struct SodClass__vt_obj {
85 \h'2n'const SodClass *_class;
89 struct SodObject__ilayout {
91 \h'4n'struct SodClass__ichain_obj {
92 \h'6n'const struct SodClass__vt_obj *_vt;
93 \h'6n'struct SodClass__islots {
94 \h'8n'const char *name;
95 \h'8n'const char *nick;
97 \h'8n'void *(*imprint)(void *\fIp\fB);
98 \h'8n'void *(*init)(void *\fIp\fB);
99 \h'8n'size_t n_supers;
100 \h'8n'const SodClass *const *supers;
102 \h'8n'const SodClass *const *cpl;
103 \h'8n'const SodClass *link;
104 \h'8n'const SodClass *head;
106 \h'8n'size_t n_chains;
107 \h'8n'const struct sod_chain *chains;
108 \h'8n'size_t off_islots;
109 \h'8n'size_t islotsz;
117 \h'2n'size_t n_classes;
118 \h'2n'const SodClass *const *classes;
119 \h'2n'size_t off_ichain;
120 \h'2n'const struct sod_vtable *vt;
121 \h'2n'size_t ichainsz;
124 extern const struct SodClass__ilayout SodClass__classobj;
125 #define SodClass__class (&SodClass__classobj.obj.cls)
129 .\"--------------------------------------------------------------------------
132 This page describes the structure and layout
133 of standard Sod objects, classes and associated metadata.
134 Note that Sod's object system is very flexible
135 and it's possible for an extension
136 to define a new root class
137 which works very differently from the standard
141 .\"--------------------------------------------------------------------------
142 .SH COMMON INSTANCE STRUCTURE
145 a pointer to an instance actually points to an
147 structure within the instances overall layout structure.
149 Instance chains contain slots and vtable pointers,
151 All instances have the basic structure of a
152 .BR "struct sod_instance" ,
153 which has the following members.
155 .B "const struct sod_vtable *_vt"
158 which has the basic structure of a
159 .BR "struct sod_vtable" ,
162 A vtable contains static metadata needed
163 for efficient conversions and
165 and pointers to the instance's class.
166 Each chain points to a different vtable
167 All vtables have the basic structure of a
168 .BR "struct sod_vtable" ,
169 which has the following members.
171 .B "const SodClass *_class"
172 A pointer to the instance's class object.
175 The offset of this chain structure
176 above the start of the overall instance layout, in bytes.
179 from the instance chain pointer
180 finds the layout base address.
182 .\"--------------------------------------------------------------------------
183 .SH BUILT-IN ROOT OBJECTS
185 This section describes the built-in classes
189 which are the standard roots of the inheritance and metaclass graphs
193 has no direct superclasses,
196 is its own metaclass.
197 It is not possible to define root classes in module files
198 because of circularities:
207 Extensions can define additional root classes,
209 and not really to be recommended.
211 .SS The SodObject class
214 class defines no slots or messages.
217 has no direct superclasses,
218 there is only one chain,
219 and no inherited slots or messages,
220 so the single chain contains only a vtable pointer.
222 Since there are no messages,
225 also has only one chain,
226 the vtable contains only the standard class pointer and offset-to-base
228 In an actual instance of
230 (why would you want one?)
231 the class pointer contains the address of
233 and the offset is zero.
235 .SS The SodClass class
238 class defines no messages,
239 but there are a number of slots.
240 Its only direct superclass is
242 and so (like its superclass) its vtable is trivial.
244 The slots defined are as follows.
247 A pointer to the class's name.
250 A pointer to the class's nickname.
253 The size in bytes required to store an instance of the class.
255 .BI "void *(*imprint)(void *" p );
256 A pointer to a function:
261 bytes of appropriately aligned memory,
262 `imprint' this memory it so that it becomes a minimally functional
263 instance of the class:
264 all of the vtable and class pointers are properly initialized,
265 but the slots are left untouched.
266 The function returns its argument
269 .BI "void *(*init)(void *" p );
270 A pointer to a function:
275 bytes of appropriately aligned memory,
276 initialize an instance of the class in it:
277 all of the vtable and class pointers are initialized,
278 as are slots for which initializers are defined.
279 Other slots are left untouched.
280 The function returns its argument
284 The number of direct superclasses.
285 (This is zero exactly in the case of
288 .B const SodClass *const *supers;
289 A pointer to an array of
291 pointers to class objects
292 listing the class's direct superclasses,
293 in the order in which they were listed in the class definition.
297 then this pointer is null.
300 The number of superclasses in the class's class precedence list.
302 .B const SodClass *const *cpl;
303 A pointer to an array of pointers to class objects
304 listing all of the class's superclasses,
305 from most- to least-specific,
306 starting with the class itself,
311 for all class objects
314 .B const SodClass *link;
315 If the class is a chain head, then this is a null pointer;
316 otherwise it points to the class's distinguished link superclass
317 (which might or might not be a direct superclass).
319 .B const SodClass *head;
320 A pointer to the least-specific class in this class's chain;
322 .IB c ->cls.head->cls.link
334 .IB c ->cls.link->cls.head \fR.
337 The number of less specific superclasses in this class's chain.
346 .IB c ->cls.link->cls.level
350 The number of chains formed by the class's superclasses.
352 .B const struct sod_chain *chains;
353 A pointer to an array of
355 structures (see below) describing the class's superclass chains,
356 in decreasing order of specificity of their most specific classes.
357 It is always the case that
358 .IB c ->cls.chains[0].classes[ c ->cls.level]
362 .B size_t off_islots;
363 The offset of the class's
365 structure relative to its containing
368 The class doesn't define any slots if and only if this is zero.
369 (The offset can't be zero because the vtable pointer is at offset zero.)
372 The size required to store the class's direct slots,
373 i.e., the size of its
376 The class doesn't define any slots if and only if this is zero.
380 structure describes an individual chain of superclasses.
381 It has the following members.
384 The number of classes in the chain.
385 This is always at least one.
387 .B const SodClass *const *classes;
388 A pointer to an array of class pointers
389 listing the classes in the chain from least- to most-specific.
391 .IB classes [ i ]->cls.head
399 .IB classes [0]->cls.link
402 .IB classes [ i ]->cls.link
404 .IB classes [ "i\fR \- 1" ]
411 .B size_t off_ichain;
414 structure for this chain.
416 .B const struct sod_vtable *vt;
417 The vtable for this chain.
418 (It is possible, therefore, to duplicate the behaviour of the
420 function by walking the chain structure.
423 function is much faster, though.)
428 structure for this chain.
430 .\"--------------------------------------------------------------------------
431 .SH CLASS AND VTABLE LAYOUT
433 The layout algorithms for Sod instances and vtables are nontrivial.
434 They are defined here in full detail,
435 since they're effectively fixed by Sod's ABI compatibility guarantees,
436 so they might as well be documented for the sake of interoperating
439 Unfortunately, the descriptions are rather complicated,
440 and, for the most part not necessary to a working understanding of Sod.
441 The skeleton structure definitions shown should be more than enough
442 for readers attempting to make sense of the generated headers and tables.
444 In the description that follows,
445 uppercase letters vary over class names,
446 while the corresponding lowercase letters indicate the class nicknames.
447 Throughout, we consider a class
449 (therefore with nickname
452 .SS Generic instance structure
453 The entire state of an instance of
455 is contained in a single structure of type
461 struct \fIC\fB__ilayout {
462 \h'2n'union \fIC\fB__ichainu_\fIh\fB {
463 \h'4n'struct \fIC\fB__ichain_\fIh\fB {
464 \h'6n'const struct \fIC\fB__vt_\fIh\fB *_vt;
465 \h'6n'struct \fIH\fB__islots \fIh\fB;
467 \h'6n'struct \fIC\fB__islots {
468 \h'8n'\fItype\fB \fIslota\fB;
473 \h'4n'struct \fIH\fB__ichain_\fIh\fB \fIh\fB;
475 \h'2n'union \fIB\fB__ichainu_\fIi\fB \fIi\fB;
479 typedef struct \fIC\fB__ichain_\fIh\fB \fIC\fB;
483 The set of superclasses of
486 can be partitioned into chains
487 by following their distinguished superclass links.
488 (Formally, the chains are the equivalence classes determined by
489 the reflexive, symmetric, transitive closure of
490 the `links to' relation.)
491 Chains are identified by naming their least specific classes;
492 the least specific class in a chain is called the
494 Suppose that the chain head of the chain containing
498 (though keep in mind that it's possible that
506 structure contains one member for each of
509 The first such member is
517 this is followed by members
523 for each other chain,
529 the tail (most-specific) class of the chain.
530 The members are in decreasing order
531 of the specificity of the chains' most-specific classes.
532 (Note that all but the first of these unions
533 has already been defined as part of
534 the definition of the corresponding
539 union contains a member for each class in the chain.
546 and this is followed by corresponding members
556 in the same chain in some (unimportant) order.
560 (and, indeed, defined in C's type system)
561 to be a pointer to the
563 .IB C __ichain_ h \fR.
567 structure contains (in order), a pointer
574 followed by a structure
584 in the same chain which defines slots,
585 from least- to most-specific;
589 then the last member is
597 structure simply contains one member for each slot defined by
599 in the order they appear in the class definition.
601 .SS Generic vtable structure
605 structure of an instance's storage
614 the vtables for the different chains
619 The instance layout split neatly into disjoint chains.
620 This is necessary because
623 must have as a prefix the
625 for each superclass in the same chain,
626 and each slot must be stored in exactly one place.
627 The layout of vtables doesn't have this second requirement:
628 it doesn't matter that there are
629 multiple method entry pointers
630 for the same effective method
631 as long as they all work correctly.
632 Indeed, it's essential that they do,
633 because each chain's method entry function
634 will need to apply a different offset to the receiver pointer
635 before invoking the effective method.
641 has the following general structure.
645 union \fIC\fB__vtu_\fIh\fB {
646 \h'2n'struct \fIC\fB__vt_\fIh\fB {
647 \h'4n'const \fIP\fB *_class;
650 \h'4n'const \fIQ\fB *_cls_\fIj\fB;
652 \h'4n'ptrdiff_t _off_\fIi\fB;
654 \h'4n'struct \fIC\fB__vtmsgs_\fIa\fB {
655 \h'6n'\fItype\fB (*\fImsg\fB)(\fIC\fB *, \fR...\fB);
662 extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
683 This is mostly an irrelevant detail,
684 whose purpose is to defend against malicious compilers:
685 pointers are always to one of the inner
688 It's important only because it's the outer
690 union which is exported by name.
691 Specifically, for each chain of
694 there is an external object
704 are respectively the most and least specific classes in the chain.
706 The first member in the
709 .I root class pointer
715 Among the superclasses of
717 there must be exactly one class
719 which itself has no direct superclasses;
724 (This is a rule enforced by the Sod translator.)
737 structure of most specific superclass
744 This is followed by the
750 which is simply the offset of the
752 structure from the instance base.
754 The rest of the vtable structure is populated
755 by walking the superclass chain containing
758 For each such superclass
760 in increasing order of specificity,
761 walk the class precedence list of
763 again starting with its least-specific superclass.
764 (This complex procedure guarantees that
765 the vtable structure for a class is a prefix of
766 the vtable structure for any of its subclasses in the same chain.)
770 be some superclass of
772 which has been encountered during this traversal.
778 Examine the superclass chains of
780 in order of decreasing specificity of their most-specific classes.
783 be the chain head of such a chain,
786 be the most specific superclass of
790 Then, if there is currently no class pointer of type
800 pointing to the appropriate
807 Examine the superclass chains of
809 in order of decreasing specificity of their most-specific classes.
812 be the chain head of such a chain.
813 If there is currently no member
822 containing the (signed) offset from the
824 structure of the chain headed by
826 to that of the chain headed by
828 within the instance's layout.
833 defines any messages,
834 and there is currently no member
849 structures contain pointers to the effective method entry functions
850 for the messages defined by a superclass.
851 There may be more than one method entry for a message,
852 but all of the entry pointers for a message appear together,
853 and entry pointers for separate messages appear
854 in the order in which the messages are defined.
855 If the receiver class has no applicable primary method for a message
856 then it's usual for the method entry pointer to be null
857 (though, as with a lot of things in Sod,
858 extensions may do something different).
860 For a standard message which takes a fixed number of arguments,
871 there is always a `main' entry point,
883 For a standard message which takes a variable number of arguments,
895 two entry points are defined:
896 the usual `main' entry point
897 which accepts a variable number of
899 and a `valist' entry point
900 which accepts an argument of type
902 in place of the variable portion of the argument list.
927 .SS Additional definitions
928 In addition to the instance and vtable structures described above,
929 the following definitions are made for each class
936 there is a macro definition
941 .IB me ->_vt-> c . m ( me ,
944 which makes sending the message
946 to an instance of (any subclass of)
951 takes a variable number of arguments,
952 the macro is more complicated
953 and is only available in compilers advertising C99 support,
954 but the effect is the same.
955 For each variable-argument message,
956 there is also an additional macro
957 for calling the `valist' entry point.
968 .IB me ->_vt-> c . m __v( me ,
972 For each proper superclass
976 there is a macro defined
979 .BI * C __CONV_ a ( C
984 which converts a (static-type) pointer to
986 to a pointer to the same actual instance,
987 but statically typed as a pointer to
989 This is most useful when
991 is not in the same chain as
993 since in-chain upcasts are both trivial and rarely needed,
994 but the full set is defined for the sake of completeness.
996 Finally, the class object is defined as
998 .B extern const struct
1004 .BI (& C __classobj. j . r )
1008 contains the entire class instance.
1009 This is usually rather unwieldy.
1012 is usable as a pointer of type
1018 is the root metaclass of
1020 i.e., the metaclass of the least specific superclass of
1023 .BR "const SodClass *" .
1025 .\"--------------------------------------------------------------------------
1029 .\"--------------------------------------------------------------------------
1031 Mark Wooding, <mdw@distorted.org.uk>
1033 .\"----- That's all, folks --------------------------------------------------