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 sections
\ref{sec:structures.layout
} are defined
36 in the 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
90 \subsection{The SodObject class
} \label{sec:structures.root.sodobject
}
93 \begin{tabular
}{p
{10pt
}p
{10pt
}}
95 struct SodObject__ilayout \
{ \\
\ind
97 struct SodObject__ichain_obj \
{ \\
\ind
98 const struct SodObject__vt_obj *_vt; \- \\
105 struct SodObject__vt_obj \
{ \\
\ind
106 const SodClass *_class; \\
111 \caption{Instance and vtable layout of @|SodObject|
}
112 \label{fig:structures.root.sodobject
}
115 \begin{describe
}[SodObject
]{cls
}
116 {[metaclass = SodClass, lisp_metaclass = sod_class
] \\
117 class SodObject \
{ \
}}
119 The @|SodObject| class defines no slots or messages. Because @|SodObject|
120 has no direct superclasses, there is only one chain, and no inherited
121 slots or messages, so the single chain contains only a vtable pointer.
123 Since there are no messages, and @|SodClass| also has only one chain, the
124 vtable contains only the standard class pointer and offset-to-base members.
125 In a direct instance of @|SodObject| (why would you want one?) the class
126 pointer contains the address of @|SodObject__class| and the offset is zero.
128 The instance and vtable layout of @|SodObject| is shown in
129 \xref{fig:structures.root.sodobject
}.
132 \subsection{The SodClass class
} \label{sec:structures.root.sodclass
}
134 \begin{describe
}[SodClass
]{cls
}
135 {class SodClass : SodObject \
{ \\
\ind
139 void *
(*imprint)(void *@<p>); \\
140 void *(*init)(void *@<p>); \\
142 const SodClass *const *supers; \\
144 const SodClass *const *cpl; \\
145 const SodClass *link; \\
146 const SodClass *head; \\
149 const struct sod_chain *chains; \\
150 size_t off_islots; \\
151 size_t islotsz; \- \\
154 The @|SodClass| class defines no messages, but there are a number of slots.
155 Its only direct superclass is @|SodObject| and so (like its superclass) its
158 The slots defined are as follows.
159 \begin{description} \let\makelabel\code
161 \item[name] A pointer to the class's name.
163 \item[nick] A pointer to the class's nickname.
165 \item[initsz] The size in bytes required to store an instance of the class.
167 \item[imprint] A pointer to a function: given a pointer @<p> to at least
168 @<initsz> bytes of appropriately aligned memory, `imprint' this memory it
169 so that it becomes a minimally functional instance of the class: all of
170 the vtable and class pointers are properly initialized, but the slots are
171 left untouched. The function returns its argument @<p>.
173 \item[init] A pointer to a function: given a pointer @<p> to at least
174 @<initsz> bytes of appropriately aligned memory, initialize an instance
175 of the class in it: all of the vtable and class pointers are initialized,
176 as are slots for which initializers are defined. Other slots are left
177 untouched. The function returns its argument @<p>.
179 \item[n_supers] The number of direct superclasses. (This is zero exactly
180 in the case of @|SodObject|.)
182 \item[supers] A pointer to an array of @<n_supers> pointers to class
183 objects listing the class's direct superclasses, in the order in which
184 they were listed in the class definition. If @<n_supers> is zero, then
185 this pointer is null.
187 \item[n_cpl] The number of superclasses in the class's class precedence
190 \item[cpl] A pointer to an array of pointers to class objects listing all
191 of the class's superclasses, from most- to least-specific, starting with
192 the class itself, so $c@->@|cls|.@|cpl|[0] = c$ for all class objects
195 \item[link] If the class is a chain head, then this is a null pointer;
196 otherwise it points to the class's distinguished link superclass (which
197 might or might not be a direct superclass).
199 \item[head] A pointer to the least-specific class in this class's chain; so
200 $c@->@|cls|.@|head|@->@|cls|.@|link|$ is always null, and either
201 $c@->@|cls|.@|link|$ is null (in which case $c@->@|cls|.@|head| = c$) or
202 $c@->@|cls|.@|head| = c@->@|cls|.@|link|@->@|cls|.@|head|$.
204 \item[level] The number of less specific superclasses in this class's
205 chain. If $c@->@|cls|.@|link|$ is null then $c@->@|cls|.@|level|$ is
206 zero; otherwise $c@->@|cls|.@|level| =
207 c@->@|cls|.@|link|@->@|cls|.@|level| + 1$.
209 \item[n_chains] The number of chains formed by the class's superclasses.
211 \item[chains] A pointer to an array of @|struct sod_chain| structures (see
212 below) describing the class's superclass chains, in decreasing order of
213 specificity of their most specific classes. It is always the case that
214 $c@->@|cls|.@|chains|[0].@|classes|[c@->@|cls|.@|level|] = c$.
216 \item[off_islots] The offset of the class's @|islots| structure relative to
217 its containing @|ichain| structure. The class doesn't define any slots
218 if and only if this is zero. (The offset can't be zero because the
219 vtable pointer is at offset zero.)
221 \item[islotsz] The size required to store the class's direct slots, i.e.,
222 the size of its @|islots| structure. The class doesn't define any slots
223 if and only if this is zero.
228 \begin{describe}[struct sod_chain]{type}
229 {struct sod_chain \{ \\ \ind
231 const SodClass *const *classes; \\
232 size_t off_ichain; \\
233 const struct sod_vtable *vt; \\
234 size_t ichainsz; \- \\
237 The @|struct sod_chain| structure describes an individual chain of
238 superclasses. It has the following members.
239 \begin{description} \let\makelabel\code
241 \item[n_classes] The number of classes in the chain. This is always at
244 \item[classes] A pointer to an array of class pointers listing the classes
245 in the chain from least- to most-specific. So
246 $@<classes>[i]@->@|cls|.@|head| = @<classes>[0]$ for all $0 \le i <
247 @<n_classes>$, $@<classes>[0]@->@|cls|.@|link|$ is always null, and
248 $@<classes>[i]@->@|cls|.@|link| = @<classes>[i - 1]$ if $1 \le i <
251 \item[off_ichain] The size of the @|ichain| structure for this chain.
253 \item[vt] The vtable for this chain. (It is possible, therefore, to
254 partially duplicate the behaviour of the @<imprint> function by walking
255 the chain structure.\footnote{%
256 There isn't enough information readily available to fill in the class
257 pointers correctly.} %
258 The @<imprint> function is much faster, though.)
260 \item[ichainsz] The size of the @|ichain| structure for this chain.
265 %%%--------------------------------------------------------------------------
266 \section{Class and vtable layout} \label{sec:structures.layout}
268 The layout algorithms for Sod instances and vtables are nontrivial. They are
269 defined here in full detail, since they're effectively fixed by Sod's ABI
270 compatibility guarantees, so they might as well be documented for the sake of
271 interoperating programs.
273 Unfortunately, the descriptions are rather complicated, and, for the most
274 part not necessary to a working understanding of Sod. The skeleton structure
275 definitions shown should be more than enough for readers attempting to make
276 sense of the generated headers and tables.
278 In the description that follows, uppercase letters vary over class names,
279 while the corresponding lowercase letters indicate the class nicknames.
280 Throughout, we consider a class $C$ (therefore with nickname $c$).
282 \subsection{Generic instance structure}
283 \label{sec:structures.layout.instance}
285 The entire state of an instance of $C$ is contained in a single structure of
286 type @|struct $C$__ilayout|.
289 struct $C$__ilayout \{ \\ \ind
290 union $C$__ichainu_$h$ \{ \\ \ind
291 struct $C$__ichain_$h$ \{ \\ \ind
292 const struct $C$__vt_$h$ *_vt; \\
293 struct $H$__islots $h$; \\
295 struct $C$__islots \{ \\ \ind
296 @<type>_1 @<slot>_1; \\
298 @<type>_n @<slot>_n; \- \\
301 struct $H$__ichain_$h$ $h$; \\
304 union $B$__ichainu_$i$ $i$; \\
308 typedef struct $C$__ichain_$h$ $C$;
311 The set of superclasses of $C$, including itself, can be partitioned into
312 chains by following their distinguished superclass links. (Formally, the
313 chains are the equivalence classes determined by the reflexive, symmetric,
314 transitive closure of the `links to' relation.) Chains are identified by
315 naming their least specific classes; the least specific class in a chain is
316 called the \emph{chain head}. Suppose that the chain head of the chain
317 containing $C$ itself is named $H$ (though keep in mind that it's possible
318 that .$H$ is in fact $C$ itself.)
320 \subsubsection{The ilayout structure}
321 The @|ilayout| structure contains one member for each of $C$'s superclass
322 chains. The first such member is
324 union $C$__ichainu_$h$ $h$;
326 described below; this is followed by members
328 union $B$__ichainu_$i$ $i$;
330 for each other chain, where $I$ is the head and $B$ the tail (most-specific)
331 class of the chain. The members are in decreasing order of the specificity
332 of the chains' most-specific classes. (Note that all but the first of these
333 unions has already been defined as part of the definition of the
336 \subsubsection{The ichainu union}
337 The @|ichainu| union contains a member for each class in the chain. The
340 struct $C$__ichain_$h$ $c$;
342 and this is followed by corresponding members
344 struct $A$__ichain_$h$ $a$;
346 for each of $C$'s superclasses $A$ in the same chain in some (unimportant)
349 \subsubsection{The ichain structure}
352 structure contains (in order), a pointer
354 const struct $C$__vt_$h$ *_vt;
356 followed by a structure
358 struct $A$__islots $a$;
360 for each superclass $A$ of $C$ in the same chain which defines slots, from
361 least- to most-specific; if $C$ defines any slots, then the last member is
363 struct $C$__islots $c$;
365 A `pointer to $C$' is always assumed (and, indeed, defined in C's
366 type system) to be a pointer to the @|struct $C$__ichain_$h$|.
368 \subsubsection{The islots structure}
369 Finally, the @|islots| structure simply contains one member for each slot
370 defined by $C$ in the order they appear in the class definition.
372 \subsection{Generic vtable structure} \label{sec:structures.layout.vtable}
374 As described above, each @|ichain| structure of an instance's storage has a
377 const struct $C$__vt_$h$ *_vt;
379 In general, the vtables for the different chains will have \emph{different}
382 The instance layout split neatly into disjoint chains. This is necessary
383 because each @|ichain| must have as a prefix the @|ichain| for each
384 superclass in the same chain, and each slot must be stored in exactly one
385 place. The layout of vtables doesn't have this second requirement: it
386 doesn't matter that there are multiple method entry pointers for the same
387 effective method as long as they all work correctly. Indeed, it's essential
388 that they do, because each chain's method entry function will need to apply a
389 different offset to the receiver pointer before invoking the effective
392 A vtable for a class $C$ with chain head $H$ has the following general
395 union $C$__vtu_$h$ \{ \\ \ind
396 struct $C$__vt_$h$ \{ \\ \ind
397 const $P$ *_class; \\
400 const $Q$ *_cls_$j$; \\
402 ptrdiff_t _off_$i$; \\
404 struct $C$__vtmsgs_$a$ \{ \\ \ind
405 @<type> (*@<msg>)($C$ *, $\dots$); \\
412 extern const union $C$__vtu_$h$ $C$__vtable_$h$;
415 \subsubsection{The vtu union}
416 The outer layer is a @|union $C$__vtu_$h$| containing a member
418 struct $A$__vt_$h$ $a$;
420 for each of $C$'s superclasses $A$ in the same chain, with $C$ itself listed
423 This is mostly an irrelevant detail,
424 whose purpose is to defend against malicious compilers:
425 pointers are always to one of the inner
428 It's important only because it's the outer
430 union which is exported by name.
431 Specifically, for each chain of
434 there is an external object
436 const union $A$__vtu_$i$ $C$__vtable_$i$;
438 where $A$ and $I$ are respectively the most and least specific classes in the
441 \subsubsection{The vt structure}
442 The first member in the @|vt| structure is the \emph{root class pointer}
446 Among the superclasses of $C$ there must be exactly one class $O$ which
447 itself has no direct superclasses; this is the \emph{root superclass} of $C$.
448 (This is a rule enforced by the Sod translator.) The metaclass $R$ of $O$ is
449 then the \emph{root metaclass} of $C$. The @|_class| member points to the
450 @|ichain| structure of most specific superclass $P$ of $M$ in the same chain
453 This is followed by the \emph{base offset}
457 which is simply the offset of the @|ichain| structure from the instance base.
459 The rest of the vtable structure is populated by walking the superclass chain
460 containing $C$ as follows. For each such superclass $B$, in increasing order
461 of specificity, walk the class precedence list of $B$, again starting with
462 its least-specific superclass. (This complex procedure guarantees that the
463 vtable structure for a class is a prefix of the vtable structure for any of
464 its subclasses in the same chain.)
466 So, let $A$ be some superclass of $C$ which has been encountered during this
471 \item Let $N$ be the metaclass of $A$. Examine the superclass chains of $N$
472 in order of decreasing specificity of their most-specific classes. Let $J$
473 be the chain head of such a chain, and let $Q$ be the most specific
474 superclass of $M$ in the same chain as $J$. Then, if there is currently no
475 class pointer of type $Q$, then add a member
479 to the vtable pointing to the appropriate @|islots| structure within $M$'s
482 \item Examine the superclass chains of $A$ in order of decreasing specificity
483 of their most-specific classes. Let $I$ be the chain head of such a chain.
484 If there is currently no member @|_off_$i$| then add a member
488 to the vtable, containing the (signed) offset from the @|ichain| structure
489 of the chain headed by $h$ to that of the chain headed by $i$ within the
492 \item If class $A$ defines any messages, and there is currently no member
493 $a$, then add a member
495 struct $C$__vtmsgs_$a$ $a$;
497 to the vtable. See below.
501 \subsubsection{The vtmsgs structure}
502 Finally, the @|vtmsgs| structures contain pointers to the effective method
503 entry functions for the messages defined by a superclass. There may be more
504 than one method entry for a message, but all of the entry pointers for a
505 message appear together, and entry pointers for separate messages appear in
506 the order in which the messages are defined. If the receiver class has no
507 applicable primary method for a message then it's usual for the method entry
508 pointer to be null (though, as with a lot of things in Sod, extensions may do
509 something different).
511 For a standard message which takes a fixed number of arguments, defined as
513 @<type>_0 $m$(@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n);
515 there is always a `main' entry point,
517 @<type>_0 $m$($C$ *me, @<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n);
520 For a standard message which takes a variable number of arguments,
523 @<type>_0 $m$(@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n, \dots);
525 two entry points are defined: the usual `main' entry point which accepts a
526 variable number of arguments, and a `valist' entry point which accepts an
527 argument of type @|va_list| in place of the variable portion of the argument
530 @<type>_0 $m$($C$ *me, @<type>_1 @<arg>_1, $\ldots$,
531 @<type>_n @<arg>_n, \dots); \\
532 @<type>_0 $m$__v($C$ *me, @<type>_1 @<arg>_1, $\ldots$,
533 @<type>_n @<arg>_n, va_list sod__ap);
536 \subsection{Additional definitions} \label{sec:structures.additional}
538 In addition to the instance and vtable structures described above, the
539 following definitions are made for each class $C$.
541 For each message $m$ directly defined by $C$ there is a macro definition
543 \#define $C$_$m$(@<me>, $\ldots$) @<me>@->_vt@->$c$.$m$(@<me>, $\ldots$)
545 which makes sending the message $m$ to an instance of (any subclass of) $C$
548 If $m$ takes a variable number of arguments, the macro is more complicated
549 and is only available in compilers advertising C99 support, but the effect is
550 the same. For each variable-argument message, there is also an additional
551 macro for calling the `valist' entry point.
553 \#define $C$_$m$__v(@<me>, $\ldots$, @<sod__ap>)
554 @<me>@->_vt@->$c$.$m$__v(@<me>, $\ldots$, @<sod__ap>)
557 For each proper superclass $A$ of $C$, there is a macro defined
559 $A$ *$C$__CONV_$a$($C$ *_obj);
561 (named in \emph{upper case}) which converts a (static-type) pointer to $C$ to
562 a pointer to the same actual instance, but statically typed as a pointer to
563 $A$. This is most useful when $A$ is not in the same chain as $C$ since
564 in-chain upcasts are both trivial and rarely needed, but the full set is
565 defined for the sake of completeness.
567 Finally, the class object is defined as
569 extern const struct $R$__ilayout $C$__classobj; \\
570 \#define $C$__class (\&$C$__classobj.$j$.$r$)
572 The exported symbol @|$C$__classobj| contains the entire class instance.
573 This is usually rather unwieldy. The macro @|$C$__class| is usable as a
574 pointer of type @|const $R$~*|, where $R$ is the root metaclass of $C$, i.e.,
575 the metaclass of the least specific superclass of $C$; usually this is
578 %%%----- That's all, folks --------------------------------------------------
582 %%% TeX-master: "sod.tex"