3 %%% In-depth exploration of the generated structures
5 %%% (c) 2015 Straylight/Edgeware
8 %%%----- Licensing notice ---------------------------------------------------
10 %%% This file is part of the Simple Object Definition system.
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 \chapter{Object structures} \label{ch:structures}
28 This chapter describes the structure and layout of standard Sod objects,
29 classes and associated metadata. Note that Sod's object system is very
30 flexible and it's possible for an extension to define a new root class which
31 works very differently from the standard @|SodObject| described here.
33 The concrete types described in \xref{sec:structures.common} and
34 \ref{sec:structures.root} are declared by the header file @|<sod/sod.h>|.
35 The definitions described in \xref{sec:structures.layout} are defined in the
36 header file generated by the containing module.
38 %%%--------------------------------------------------------------------------
39 \section{Common instance structure} \label{sec:structures.common}
41 As described below, a pointer to an instance actually points to an
42 \emph{instance chain} structure within the instances overall layout
45 Instance chains contain slots and vtable pointers, as described below. All
46 instances have the basic structure of a @|struct sod_instance|.
48 \begin{describe}[struct sod_instance]{type}
49 {struct sod_instance \{ \\ \ind
50 const struct sod_vtable *_vt; \- \\
53 The basic structure of all instances. Members are as follows.
54 \begin{description} \let\makelabel\code
55 \item[_vt] A pointer to a \emph{vtable}, which has the basic structure of a
56 @|struct sod_vtable|, described below.
60 \begin{describe}[struct sod_vtable]{type}
61 {struct sod_vtable \{ \\ \ind
62 const SodClass *_class; \\
66 A vtable contains static metadata needed for efficient conversions and
67 message dispatch, and pointers to the instance's class. Each chain points
68 to a different vtable. All vtables have the basic structure of a @|struct
69 sod_vtable|, which has the following members.
70 \begin{description} \let\makelabel\code
71 \item[_class] A pointer to the instance's class object.
72 \item[_base] The offset of this chain structure above the start of the
73 overall instance layout, in bytes. Subtracting @|_base| from the
74 instance chain pointer finds the layout base address.
78 %%%--------------------------------------------------------------------------
79 \section{Built-in root objects} \label{sec:structures.root}
81 This section describes the built-in classes @|SodObject| and @|SodClass|,
82 which are the standard roots of the inheritance and metaclass graphs
83 respectively. Specifically, @|SodObject| has no direct superclasses, and
84 @|SodClass| is its own metaclass. It is not possible to define root classes
85 in module files because of circularities: @|SodObject| has @|SodClass| as its
86 metaclass, and @|SodClass| is a subclass of @|SodObject|. Extensions can
87 define additional root classes, but this is tricky, and not really to be
91 \subsection{The SodObject class} \label{sec:structures.root.sodobject}
94 \begin{tabular}{p{10pt}p{10pt}}
96 struct SodObject__ilayout \{ \\ \ind
98 struct SodObject__ichain_obj \{ \\ \ind
99 const struct SodObject__vt_obj *_vt; \- \\
106 struct SodObject__vt_obj \{ \\ \ind
107 const SodClass *_class; \\
109 struct SodObject__vtmsgs_obj \{ \\ \ind
110 void (*init)(SodObject *me, ...); \\
111 void (*init__v)(SodObject *me, va_list); \- \\
116 \caption{Instance and vtable layout of @|SodObject|}
117 \label{fig:structures.root.sodobject}
120 \begin{describe}[SodObject]{cls}
121 {[nick = obj, metaclass = SodClass, lisp_metaclass = sod_class] \\
122 class SodObject \{ \\ \ind
126 The @|SodObject| class defines no slots. Because @|SodObject| has no
127 direct superclasses, there is only one chain, and no inherited slots or
128 messages, so the single chain contains only a vtable pointer.
130 Since @|SodClass| also has only one chain, the vtable contains only the
131 standard class pointer and offset-to-base members. In a direct instance of
132 @|SodObject| (why would you want one?) the class pointer contains the
133 address of @|SodObject__class| and the offset is zero.
135 The instance and vtable layout of @|SodObject| is shown in
136 \xref{fig:structures.root.sodobject}.
138 The following message is defined.
140 \begin{describe}[obj.init]{msg}{void init(?);}
141 Initialize a newly allocated instance.
143 This message uses a custom method combination which works like the
144 standard method combination except that default behaviour specific to the
145 receiver's direct class is invoked if no primary or around method
146 overrides. This default behaviour may be invoked multiple times if some
147 method calls on its @|next_method| function more than once.
149 This default behaviour is to initialize the instance's slots using the
150 defined slot initializers: each slot is initialized using the most
151 specific applicable initializer, if any. Slots without an initializer
152 are left uninitialized.
154 Slots are initialized in reverse-precedence order of their defining
155 classes; i.e., slots defined by a less specific superclass are
156 initialized earlier than slots defined by a more specific superclass.
157 Slots defined by the same class are initialized in the order in which
158 they appear in the class definition.
160 There are no standard keyword arguments; methods on subclasses are free
161 to introduce their own in the usual way.
163 It is usual to provide complex initialization behaviour as @|after|
164 methods. This ensures that slots have been initialized as necessary
165 before the method executes.
167 For more details on instance construction, see
168 \xref{sec:concepts.lifecycle.birth}.
173 \subsection{The SodClass class} \label{sec:structures.root.sodclass}
175 \begin{describe}[SodClass]{cls}
176 {[nick = cls, link = SodObject] \\
177 class SodClass : SodObject \{ \\ \ind
181 void *(*imprint)(void *@<p>); \\
183 const SodClass *const *supers; \\
185 const SodClass *const *cpl; \\
186 const SodClass *link; \\
187 const SodClass *head; \\
190 const struct sod_chain *chains; \\
191 size_t off_islots; \\
192 size_t islotsz; \- \\
195 The @|SodClass| class defines no additional messages , but there are a
196 number of slots. Its only direct superclass is @|SodObject| and so (like
197 its superclass) its vtable is simple.
199 The slots defined are as follows.
200 \begin{description} \let\makelabel\code
202 \item[name] A pointer to the class's name.
204 \item[nick] A pointer to the class's nickname.
206 \item[initsz] The size in bytes required to store an instance of the class.
208 \item[imprint] A pointer to a function: given a pointer @<p> to at least
209 @<initsz> bytes of appropriately aligned memory, `imprint' this memory it
210 so that it becomes a minimally functional instance of the class: all of
211 the vtable and class pointers are properly initialized, but the slots are
212 left untouched. The function returns its argument @<p>.
214 \item[n_supers] The number of direct superclasses. (This is zero exactly
215 in the case of @|SodObject|.)
217 \item[supers] A pointer to an array of @<n_supers> pointers to class
218 objects listing the class's direct superclasses, in the order in which
219 they were listed in the class definition. If @<n_supers> is zero, then
220 this pointer is null.
222 \item[n_cpl] The number of superclasses in the class's class precedence
225 \item[cpl] A pointer to an array of pointers to class objects listing all
226 of the class's superclasses, from most- to least-specific, starting with
227 the class itself, so $@|$c$@->cls.cpl[0]| = c$ for all class objects
230 \item[link] If the class is a chain head, then this is a null pointer;
231 otherwise it points to the class's distinguished link superclass (which
232 might or might not be a direct superclass).
234 \item[head] A pointer to the least-specific class in this class's chain; so
235 @|$c$@->cls.head@->cls.link| is always null, and either @|$c$@->cls.link|
236 is null (in which case $@|$c$@->cls.head| = c$) or $@|$c$@->cls.head| =
237 @|$c$@->cls.link@->cls.head|$.
239 \item[level] The number of less specific superclasses in this class's
240 chain. If @|$c$@->cls.link| is null then @|$c$@->cls.level| is zero;
241 otherwise $@|$c$@->cls.level| = @|$c$@->cls.link@->cls.level| + 1$.
243 \item[n_chains] The number of chains formed by the class's superclasses.
245 \item[chains] A pointer to an array of @|struct sod_chain| structures (see
246 below) describing the class's superclass chains, in decreasing order of
247 specificity of their most specific classes. It is always the case that
248 $@|$c$@->cls.chains[0].classes[$c$@->cls.level]| = c$.
250 \item[off_islots] The offset of the class's @|islots| structure relative to
251 its containing @|ichain| structure. The class doesn't define any slots
252 if and only if this is zero. (The offset can't be zero because the
253 vtable pointer is at offset zero.)
255 \item[islotsz] The size required to store the class's direct slots, i.e.,
256 the size of its @|islots| structure. The class doesn't define any slots
257 if and only if this is zero.
262 \begin{describe}[struct sod_chain]{type}
263 {struct sod_chain \{ \\ \ind
265 const SodClass *const *classes; \\
266 size_t off_ichain; \\
267 const struct sod_vtable *vt; \\
268 size_t ichainsz; \- \\
271 The @|struct sod_chain| structure describes an individual chain of
272 superclasses. It has the following members.
273 \begin{description} \let\makelabel\code
275 \item[n_classes] The number of classes in the chain. This is always at
278 \item[classes] A pointer to an array of class pointers listing the classes
279 in the chain from least- to most-specific. So
280 $@|@<classes>[$i$]@->cls.head| = @|@<classes>[0]|$ for all $0 \le i <
281 @<n_classes>$, @|@<classes>[0]@->cls.link| is always null, and
282 $@|@<classes>[$i$]@->cls.link| = @|@<classes>[$i - 1$]|$ if $1 \le i <
285 \item[off_ichain] The size of the @|ichain| structure for this chain.
287 \item[vt] The vtable for this chain. (It is possible, therefore, to
288 partially duplicate the behaviour of the @<imprint> function by walking
289 the chain structure.\footnote{%
290 There isn't enough information readily available to fill in the class
291 pointers correctly.} %
292 The @<imprint> function is much faster, though.)
294 \item[ichainsz] The size of the @|ichain| structure for this chain.
299 %%%--------------------------------------------------------------------------
300 \section{Class and vtable layout} \label{sec:structures.layout}
302 The layout algorithms for Sod instances and vtables are nontrivial. They are
303 defined here in full detail, since they're effectively fixed by Sod's ABI
304 compatibility guarantees, so they might as well be documented for the sake of
305 interoperating programs.
307 Unfortunately, the descriptions are rather complicated, and, for the most
308 part not necessary to a working understanding of Sod. The skeleton structure
309 definitions shown should be more than enough for readers attempting to make
310 sense of the generated headers and tables.
312 In the description that follows, uppercase letters vary over class names,
313 while the corresponding lowercase letters indicate the class nicknames.
314 Throughout, we consider a class $C$ (therefore with nickname $c$).
317 \subsection{Generic instance structure}
318 \label{sec:structures.layout.instance}
320 The entire state of an instance of $C$ is contained in a single structure of
321 type @|struct $C$__ilayout|.
324 struct $C$__ilayout \{ \\ \ind
325 union $C$__ichainu_$h$ \{ \\ \ind
326 struct $C$__ichain_$h$ \{ \\ \ind
327 const struct $C$__vt_$h$ *_vt; \\
328 struct $H$__islots $h$; \\
330 struct $C$__islots \{ \\ \ind
331 @<type>_1 @<slot>_1; \\
333 @<type>_n @<slot>_n; \- \\
336 struct $H$__ichain_$h$ $h$; \\
339 union $B$__ichainu_$i$ $i$; \\
343 typedef struct $C$__ichain_$h$ $C$;
346 The set of superclasses of $C$, including itself, can be partitioned into
347 chains by following their distinguished superclass links. (Formally, the
348 chains are the equivalence classes determined by the reflexive, symmetric,
349 transitive closure of the `links to' relation.) Chains are identified by
350 naming their least specific classes; the least specific class in a chain is
351 called the \emph{chain head}. Suppose that the chain head of the chain
352 containing $C$ itself is named $H$ (though keep in mind that it's possible
353 that .$H$ is in fact $C$ itself.)
355 \subsubsection{The ilayout structure}
356 The @|ilayout| structure contains one member for each of $C$'s superclass
357 chains. The first such member is
359 union $C$__ichainu_$h$ $h$;
361 described below; this is followed by members
363 union $B$__ichainu_$i$ $i$;
365 for each other chain, where $I$ is the head and $B$ the tail (most-specific)
366 class of the chain. The members are in decreasing order of the specificity
367 of the chains' most-specific classes. (Note that all but the first of these
368 unions has already been defined as part of the definition of the
371 \subsubsection{The ichainu union}
372 The @|ichainu| union contains a member for each class in the chain. The
375 struct $C$__ichain_$h$ $c$;
377 and this is followed by corresponding members
379 struct $A$__ichain_$h$ $a$;
381 for each of $C$'s superclasses $A$ in the same chain in some (unimportant)
384 \subsubsection{The ichain structure}
387 structure contains (in order), a pointer
389 const struct $C$__vt_$h$ *_vt;
391 followed by a structure
393 struct $A$__islots $a$;
395 for each superclass $A$ of $C$ in the same chain which defines slots, from
396 least- to most-specific; if $C$ defines any slots, then the last member is
398 struct $C$__islots $c$;
400 A `pointer to $C$' is always assumed (and, indeed, defined in C's
401 type system) to be a pointer to the @|struct $C$__ichain_$h$|.
403 \subsubsection{The islots structure}
404 Finally, the @|islots| structure simply contains one member for each slot
405 defined by $C$ in the order they appear in the class definition.
408 \subsection{Generic vtable structure} \label{sec:structures.layout.vtable}
410 As described above, each @|ichain| structure of an instance's storage has a
413 const struct $C$__vt_$h$ *_vt;
415 In general, the vtables for the different chains will have \emph{different}
418 The instance layout split neatly into disjoint chains. This is necessary
419 because each @|ichain| must have as a prefix the @|ichain| for each
420 superclass in the same chain, and each slot must be stored in exactly one
421 place. The layout of vtables doesn't have this second requirement: it
422 doesn't matter that there are multiple method entry pointers for the same
423 effective method as long as they all work correctly. Indeed, it's essential
424 that they do, because each chain's method entry function will need to apply a
425 different offset to the receiver pointer before invoking the effective
428 A vtable for a class $C$ with chain head $H$ has the following general
431 union $C$__vtu_$h$ \{ \\ \ind
432 struct $C$__vt_$h$ \{ \\ \ind
433 const $P$ *_class; \\
436 const $Q$ *_cls_$j$; \\
438 ptrdiff_t _off_$i$; \\
440 struct $C$__vtmsgs_$a$ \{ \\ \ind
441 @<type> (*@<msg>)($C$ *, $\dots$); \\
448 extern const union $C$__vtu_$h$ $C$__vtable_$h$;
451 \subsubsection{The vtu union}
452 The outer layer is a @|union $C$__vtu_$h$| containing a member
454 struct $A$__vt_$h$ $a$;
456 for each of $C$'s superclasses $A$ in the same chain, with $C$ itself listed
459 This is mostly an irrelevant detail,
460 whose purpose is to defend against malicious compilers:
461 pointers are always to one of the inner
464 It's important only because it's the outer
466 union which is exported by name.
467 Specifically, for each chain of
470 there is an external object
472 const union $A$__vtu_$i$ $C$__vtable_$i$;
474 where $A$ and $I$ are respectively the most and least specific classes in the
477 \subsubsection{The vt structure}
478 The first member in the @|vt| structure is the \emph{root class pointer}
482 Among the superclasses of $C$ there must be exactly one class $O$ which
483 itself has no direct superclasses; this is the \emph{root superclass} of $C$.
484 (This is a rule enforced by the Sod translator.) The metaclass $R$ of $O$ is
485 then the \emph{root metaclass} of $C$. The @|_class| member points to the
486 @|ichain| structure of most specific superclass $P$ of $M$ in the same chain
489 This is followed by the \emph{base offset}
493 which is simply the offset of the @|ichain| structure from the instance base.
495 The rest of the vtable structure is populated by walking the superclass chain
496 containing $C$ as follows. For each such superclass $B$, in increasing order
497 of specificity, walk the class precedence list of $B$, again starting with
498 its least-specific superclass. (This complex procedure guarantees that the
499 vtable structure for a class is a prefix of the vtable structure for any of
500 its subclasses in the same chain.)
502 So, let $A$ be some superclass of $C$ which has been encountered during this
507 \item Let $N$ be the metaclass of $A$. Examine the superclass chains of $N$
508 in order of decreasing specificity of their most-specific classes. Let $J$
509 be the chain head of such a chain, and let $Q$ be the most specific
510 superclass of $M$ in the same chain as $J$. Then, if there is currently no
511 class pointer of type $Q$, then add a member
515 to the vtable pointing to the appropriate @|islots| structure within $M$'s
518 \item Examine the superclass chains of $A$ in order of decreasing specificity
519 of their most-specific classes. Let $I$ be the chain head of such a chain.
520 If there is currently no member @|_off_$i$| then add a member
524 to the vtable, containing the (signed) offset from the @|ichain| structure
525 of the chain headed by $h$ to that of the chain headed by $i$ within the
528 \item If class $A$ defines any messages, and there is currently no member
529 $a$, then add a member
531 struct $C$__vtmsgs_$a$ $a$;
533 to the vtable. See below.
537 \subsubsection{The vtmsgs structure}
538 Finally, the @|vtmsgs| structures contain pointers to the effective method
539 entry functions for the messages defined by a superclass. There may be more
540 than one method entry for a message, but all of the entry pointers for a
541 message appear together, and entry pointers for separate messages appear in
542 the order in which the messages are defined. If the receiver class has no
543 applicable primary method for a message then it's usual for the method entry
544 pointer to be null (though, as with a lot of things in Sod, extensions may do
545 something different).
547 For a standard message which takes a fixed number of arguments, defined as
549 @<type>_0 $m$(@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n);
551 there is always a `main' entry point,
553 @<type>_0 $m$($C$ *me, @<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n);
556 For a standard message which takes a variable number of arguments,
559 @<type>_0 $m$(@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n, \dots);
561 or a standard message which takes keyword arguments, defined as
563 @<type>_0 $m$(\=@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n? \+ \\
564 @<type>_{n+1} @<kw>_{n+1} @[= @<dflt>_{n+1}@], $\ldots$,
565 @<type>_m @<kw>_m @[= @<dflt>_m@]);
567 two entry points are defined: the usual `main' entry point which accepts a
568 variable number of arguments, and a `valist' entry point which accepts an
569 argument of type @|va_list| in place of the variable portion of the argument
572 @<type>_0 $m$($C$ *me, @<type>_1 @<arg>_1, $\ldots$,
573 @<type>_n @<arg>_n, \dots); \\
574 @<type>_0 $m$__v($C$ *me, @<type>_1 @<arg>_1, $\ldots$,
575 @<type>_n @<arg>_n, va_list sod__ap);
579 \subsection{Additional definitions} \label{sec:structures.layout.additional}
581 In addition to the instance and vtable structures described above, the
582 following definitions are made for each class $C$.
584 For each message $m$ directly defined by $C$ there is a macro definition
586 \#define $C$_$m$(@<me>, $\ldots$) @<me>@->_vt@->$c$.$m$(@<me>, $\ldots$)
588 which makes sending the message $m$ to an instance of (any subclass of) $C$
591 If $m$ takes a variable number of arguments, or keyword arguments, the macro
592 is more complicated and is only available in compilers advertising C99
593 support, but the effect is the same. For each variable-argument message,
594 there is also an additional macro for calling the `valist' entry point.
596 \#define $C$_$m$__v(@<me>, $\ldots$, @<sod__ap>)
597 @<me>@->_vt@->$c$.$m$__v(@<me>, $\ldots$, @<sod__ap>)
600 For each proper superclass $A$ of $C$, there is a macro defined
602 $A$ *$C$__CONV_$a$($C$ *_obj);
604 (named in \emph{upper case}) which converts a (static-type) pointer to $C$ to
605 a pointer to the same actual instance, but statically typed as a pointer to
606 $A$. This is most useful when $A$ is not in the same chain as $C$ since
607 in-chain upcasts are both trivial and rarely needed, but the full set is
608 defined for the sake of completeness.
610 Finally, the class object is defined as
612 extern const struct $R$__ilayout $C$__classobj; \\
613 \#define $C$__class (\&$C$__classobj.$j$.$r$)
615 The exported symbol @|$C$__classobj| contains the entire class instance.
616 This is usually rather unwieldy. The macro @|$C$__class| is usable as a
617 pointer of type @|const $R$~*|, where $R$ is the root metaclass of $C$, i.e.,
618 the metaclass of the least specific superclass of $C$; usually this is
621 %%%----- That's all, folks --------------------------------------------------
625 %%% TeX-master: "sod.tex"