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;
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);
79 struct SodObject__ilayout {
81 \h'4n'struct SodObject__ichain_obj {
82 \h'6n'const struct SodObject__vt_obj *_vt;
87 extern const struct SodClass__ilayout SodObject__classobj;
88 #define SodObject__class (&SodObject__classobj.obj.cls)
90 struct SodClass__vt_obj {
91 \h'2n'const SodClass *_class;
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);
100 struct SodClass__ilayout {
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;
109 \h'8n'void *(*imprint)(void *\fIp\fB);
110 \h'8n'size_t n_supers;
111 \h'8n'const SodClass *const *supers;
113 \h'8n'const SodClass *const *cpl;
114 \h'8n'const SodClass *link;
115 \h'8n'const SodClass *head;
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;
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;
135 extern const struct SodClass__ilayout SodClass__classobj;
136 #define SodClass__class (&SodClass__classobj.obj.cls)
140 .\"--------------------------------------------------------------------------
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
152 .\"--------------------------------------------------------------------------
153 .SH COMMON INSTANCE STRUCTURE
156 a pointer to an instance actually points to an
158 structure within the instances overall layout structure.
160 Instance chains contain slots and vtable pointers,
162 All instances have the basic structure of a
163 .BR "struct sod_instance" ,
164 which has the following members.
166 .B "const struct sod_vtable *_vt"
169 which has the basic structure of a
170 .BR "struct sod_vtable" ,
173 A vtable contains static metadata needed
174 for efficient conversions and
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.
182 .B "const SodClass *_class"
183 A pointer to the instance's class object.
186 The offset of this chain structure
187 above the start of the overall instance layout, in bytes.
190 from the instance chain pointer
191 finds the layout base address.
193 .\"--------------------------------------------------------------------------
194 .SH BUILT-IN ROOT OBJECTS
196 This section describes the built-in classes
200 which are the standard roots of the inheritance and metaclass graphs
204 has no direct superclasses,
207 is its own metaclass.
208 It is not possible to define root classes in module files
209 because of circularities:
218 Extensions can define additional root classes,
220 and not really to be recommended.
222 .SS The SodObject class
225 class defines no slots.
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.
235 also has only one chain,
236 the vtable contains only the standard class pointer and offset-to-base
238 In an actual instance of
240 (why would you want one?)
241 the class pointer contains the address of
243 and the offset is zero.
247 message is used to initialize a newly allocated instance.
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
257 function more than once.
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,
265 Slots without an initializer
266 are left uninitialized.
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.
276 There are no standard keyword arguments;
277 methods on subclasses are free to
278 introduce their own in the usual way.
280 It is usual to provide complex initialization behaviour as
283 This ensures that slots have been initialized as necessary
284 before the method executes.
288 message is used to tear down an instance which is no longer required.
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.
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,
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.
310 It is usual to provide complex teardown behaviour as
313 Logic to decide whether to allow deallocation
314 is usually implemented as
318 .SS The SodClass class
321 class defines no messages,
322 but there are a number of slots.
323 Its only direct superclass is
325 and so (like its superclass) its vtable is trivial.
327 The slots defined are as follows.
330 A pointer to the class's name.
333 A pointer to the class's nickname.
336 The size in bytes required to store an instance of the class.
339 A sufficient alignment for the class's instance storage.
341 .BI "void *(*imprint)(void *" p );
342 A pointer to a function:
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
356 The number of direct superclasses.
357 (This is zero exactly in the case of
360 .B const SodClass *const *supers;
361 A pointer to an array of
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.
369 then this pointer is null.
372 The number of superclasses in the class's class precedence list.
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,
383 for all class objects
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).
391 .B const SodClass *head;
392 A pointer to the least-specific class in this class's chain;
394 .IB c ->cls.head->cls.link
406 .IB c ->cls.link->cls.head \fR.
409 The number of less specific superclasses in this class's chain.
418 .IB c ->cls.link->cls.level
422 The number of chains formed by the class's superclasses.
424 .B const struct sod_chain *chains;
425 A pointer to an array of
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]
434 .B size_t off_islots;
435 The offset of the class's
437 structure relative to its containing
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.)
444 The size required to store the class's direct slots,
445 i.e., the size of its
448 The class doesn't define any slots if and only if this is zero.
452 structure describes an individual chain of superclasses.
453 It has the following members.
456 The number of classes in the chain.
457 This is always at least one.
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.
463 .IB classes [ i ]->cls.head
471 .IB classes [0]->cls.link
474 .IB classes [ i ]->cls.link
476 .IB classes [ "i\fR \- 1" ]
483 .B size_t off_ichain;
486 structure for this chain.
488 .B const struct sod_vtable *vt;
489 The vtable for this chain.
490 (It is possible, therefore, to duplicate the behaviour of the
492 function by walking the chain structure.
495 function is much faster, though.)
500 structure for this chain.
502 .\"--------------------------------------------------------------------------
503 .SH CLASS AND VTABLE LAYOUT
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
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.
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
521 (therefore with nickname
524 .SS Generic instance structure
525 The entire state of an instance of
527 is contained in a single structure of type
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;
539 \h'6n'struct \fIC\fB__islots {
540 \h'8n'\fItype\fB \fIslota\fB;
545 \h'4n'struct \fIA\fB__ichain_\fIh\fB \fIa\fB;
547 \h'2n'union \fIB\fB__ichainu_\fIi\fB \fIi\fB;
551 typedef struct \fIC\fB__ichain_\fIh\fB \fIC\fB;
555 The set of superclasses of
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
566 Suppose that the chain head of the chain containing
570 (though keep in mind that it's possible that
578 structure contains one member for each of
581 The first such member is
589 this is followed by members
595 for each other chain,
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
611 union contains a member for each class in the chain.
618 and this is followed by corresponding members
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).
635 structure contains (in order), a pointer
642 followed by a structure
652 in the same chain which defines slots,
653 from least- to most-specific;
657 then the last member is
666 (and, indeed, defined in C's type system)
667 to be a pointer to the
669 .IB C __ichain_ h \fR.
673 structure simply contains one member for each slot defined by
675 in the order they appear in the class definition.
677 .SS Generic vtable structure
681 structure of an instance's storage
690 the vtables for the different chains
695 The instance layout splits neatly into disjoint chains.
696 This is necessary because
699 must have as a prefix the
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.
717 has the following general structure.
721 union \fIC\fB__vtu_\fIh\fB {
722 \h'2n'struct \fIC\fB__vt_\fIh\fB {
723 \h'4n'const \fIP\fB *_class;
726 \h'4n'const \fIQ\fB *_cls_\fIj\fB;
728 \h'4n'ptrdiff_t _off_\fIi\fB;
730 \h'4n'struct \fIC\fB__vtmsgs_\fIa\fB {
731 \h'6n'\fItype\fB (*\fImsg\fB)(\fIC\fB *, \fR...\fB);
738 extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
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
770 It's important only because it's the outer
772 union which is exported by name.
773 Specifically, for each chain of
776 there is an external object
786 are respectively the most and least specific classes in the chain.
788 The first member in the
791 .I root class pointer
797 Among the superclasses of
799 there must be exactly one class
801 which itself has no direct superclasses;
806 (This is a rule enforced by the Sod translator.)
819 structure of most specific superclass
826 This is followed by the
832 which is simply the offset of the
834 structure from the instance base.
836 The rest of the vtable structure is populated
837 by walking the superclass chain containing
840 For each such superclass
842 in increasing order of specificity,
843 walk the class precedence list of
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.)
852 be some superclass of
854 which has been encountered during this traversal.
860 Examine the superclass chains of
862 in order of decreasing specificity of their most-specific classes.
865 be the chain head of such a chain,
868 be the most specific superclass of
872 If there is currently no class pointer
873 for the chain headed by
883 pointing to the appropriate
890 is the most specific superclass of
896 Examine the superclass chains of
898 in order of decreasing specificity of their most-specific classes.
901 be the chain head of such a chain.
902 If there is currently no member
911 containing the (signed) offset from the
913 structure of the chain headed by
915 to that of the chain headed by
917 within the instance's layout.
922 defines any messages,
923 and there is currently no member
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).
949 For a standard message which takes a fixed number of arguments,
960 there is always a `main' entry point,
972 For a standard message which takes a variable number of arguments,
984 or a standard message which takes keyword arguments,
1005 two entry points are defined:
1006 the usual `main' entry point
1007 which accepts a variable number of
1009 and a `valist' entry point
1010 which accepts an argument of type
1012 in place of the variable portion of the argument list
1038 .SS Additional definitions
1039 In addition to the instance and vtable structures described above,
1040 the following definitions are made for each class
1047 there is a macro definition
1052 .IB me ->_vt-> c . m ( me ,
1055 which makes sending the message
1057 to an instance of (any subclass of)
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.
1080 .IB me ->_vt-> c . m __v( me ,
1084 For each proper superclass
1088 there is a macro defined
1091 .BI * C __CONV_ a ( C
1096 which converts a (static-type) pointer to
1098 to a pointer to the same actual instance,
1099 but statically typed as a pointer to
1101 This is most useful when
1103 is not in the same chain as
1105 since in-chain upcasts are both trivial and rarely needed,
1106 but the full set is defined for the sake of completeness.
1108 Finally, the class object is defined as
1110 .B extern const struct
1116 .BI (& C __classobj. j . r )
1120 .BI (& C __classobj. k . n )
1126 contains the entire class instance.
1127 This is usually rather unwieldy.
1130 is usable as a pointer of type
1136 is the root metaclass of
1138 i.e., the metaclass of the least specific superclass of
1141 .BR "const SodClass\ *" .
1146 is defined, usable as a pointer of type
1154 are the chain's head and tail classes
1155 (i.e., the least- and most-specific classes in the chain)
1161 i.e., in the common case where
1163 metaclass is precisely the root metaclass,
1166 macro is already sufficient.
1168 .\"--------------------------------------------------------------------------
1172 .\"--------------------------------------------------------------------------
1174 Mark Wooding, <mdw@distorted.org.uk>
1176 .\"----- That's all, folks --------------------------------------------------