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
}{type
}[struct sod_instance
]
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
}{type
}[struct sod_vtable
]
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 The class definitions shown in the synopses are intended to be informative,
91 but are fictional and can't really work: these classes are really defined by
92 Lisp code in the Sod translator, in order to deal with the circularities
93 involved at the top of the class/metaclass graph (see
94 \xref{sec:concepts.metaclasses.runtime
}).
97 \subsection{The SodObject class
} \label{sec:structures.root.sodobject
}
100 \begin{tabular
}{p
{10pt
}p
{10pt
}}
102 struct SodObject__ilayout \
{ \\
\ind
104 struct SodObject__ichain_obj \
{ \\
\ind
105 const struct SodObject__vt_obj *_vt; \-\\
112 struct SodObject__vt_obj \
{ \\
\ind
113 const SodClass *_class; \\
115 struct SodObject__vtmsgs_obj \
{ \\
\ind
116 void
(*init)(SodObject *me, ...); \\
117 void (*init__v)(SodObject *me, va_list); \\
118 int (*teardown)(SodObject *me); \-\\
123 \caption{Instance and vtable layout of @|SodObject|}
124 \label{fig:structures.root.sodobject}
127 \begin{describe}{cls}[SodObject]
128 {[nick = obj, metaclass = SodClass,
129 lisp_metaclass = sod_class] \\
130 class SodObject \{ \\ \ind
134 The @|SodObject| class defines no slots. Because @|SodObject| has no
135 direct superclasses, there is only one chain, and no inherited slots or
136 messages, so the single chain contains only a vtable pointer.
138 Since @|SodClass| also has only one chain, the vtable contains only the
139 standard class pointer and offset-to-base members. In a direct instance of
140 @|SodObject| (why would you want one?) the class pointer contains the
141 address of @|SodObject__class| and the offset is zero.
143 The instance and vtable layout of @|SodObject| is shown in
144 \xref{fig:structures.root.sodobject}.
146 The following messages are defined.
148 \begin{describe}{msg}[obj.init]{void init(?);}
149 Initialize a newly allocated instance.
151 This message uses a custom method combination which works like the
152 standard method combination except that default behaviour specific to the
153 receiver's direct class is invoked if no primary or around method
154 overrides. This default behaviour may be invoked multiple times if some
155 method calls on its @|next_method| function more than once.
157 This default behaviour is to initialize the instance's slots using the
158 defined slot initializers, and execute the initialization fragments.
159 Each slot is initialized using the most specific applicable initializer,
160 if any. Slots without an initializer are left uninitialized.
162 Slots are initialized and initialization fragments executed together, a
163 superclass at a time: first, the superclass's slots are initialized (if
164 any); then the superclass's initialization fragments (if any) are
165 executed, starting with the least specific superclass first. Slots and
166 initialization fragments defined by the same class are processed in the
167 order in which they appear in the class definition.
169 There are no standard keyword arguments; methods on subclasses are free
170 to introduce their own in the usual way.
172 It is usual to provide complex initialization behaviour as @|after|
173 methods. This ensures that slots have been initialized as necessary
174 before the method executes.
176 For more details on instance construction, see
177 \xref{sec:concepts.lifecycle.birth}.
180 \begin{describe}{msg}[obj.teardown]{int teardown();}
181 Teardown an instance which is no longer required.
183 The message returns an integer flag. A zero value means that the
184 instance is safe to deallocate. A nonzero value means that the instance
185 should not be deallocated, and that it is safe for the caller to simply
186 forget about it. This simple protocol may be used, for example, to
187 implement a reference-counting system.
189 This message uses a custom method combination which works like the
190 standard method combination except that default behaviour is invoked if
191 no primary or around method overrides.
193 This default behaviour is to execute each superclass's teardown
194 fragments, most specific first, and then return zero to indicate that the
195 object is ready for deallocation. Teardown fragments defined by the same
196 class are processed in the order in which they appear in the class
199 It is usual to provide complex teardown behaviour as @|before| methods.
200 Logic to decide whether to allow deallocation is usually implemented as
206 \subsection{The SodClass class} \label{sec:structures.root.sodclass}
208 \begin{describe}{cls}[SodClass]
209 {[nick = cls, link = SodObject] \\
210 class SodClass: SodObject \{ \\ \ind
215 void *(*imprint)(void *@<p>); \\
217 const SodClass *const *supers; \\
219 const SodClass *const *cpl; \\
220 const SodClass *link; \\
221 const SodClass *head; \\
224 const struct sod_chain *chains; \\
225 size_t off_islots; \\
229 The @|SodClass| class defines no additional messages , but there are a
230 number of slots. Its only direct superclass is @|SodObject| and so (like
231 its superclass) its vtable is simple.
233 The slots defined are as follows.
234 \begin{description} \let\makelabel\code
236 \item[name] A pointer to the class's name.
238 \item[nick] A pointer to the class's nickname.
240 \item[initsz] The size in bytes required to store an instance of the class.
242 \item[align] A sufficient alignment for the class's instance storage.
244 \item[imprint] A pointer to a function: given a pointer @<p> to at least
245 @<initsz> bytes of appropriately aligned memory, `imprint' this memory it
246 so that it becomes a minimally functional instance of the class: all of
247 the vtable and class pointers are properly initialized, but the slots are
248 left untouched. The function returns its argument @<p>.
250 \item[n_supers] The number of direct superclasses. (This is zero exactly
251 in the case of @|SodObject|.)
253 \item[supers] A pointer to an array of @<n_supers> pointers to class
254 objects listing the class's direct superclasses, in the order in which
255 they were listed in the class definition. If @<n_supers> is zero, then
256 this pointer is null.
258 \item[n_cpl] The number of superclasses in the class's class precedence
261 \item[cpl] A pointer to an array of pointers to class objects listing all
262 of the class's superclasses, from most- to least-specific, starting with
263 the class itself, so $@|$c$@->cls.cpl[0]| = c$ for all class objects
266 \item[link] If the class is a chain head, then this is a null pointer;
267 otherwise it points to the class's distinguished link superclass (which
268 might or might not be a direct superclass).
270 \item[head] A pointer to the least-specific class in this class's chain; so
271 @|$c$@->cls.head@->cls.link| is always null, and either @|$c$@->cls.link|
272 is null (in which case $@|$c$@->cls.head| = c$) or $@|$c$@->cls.head| =
273 @|$c$@->cls.link@->cls.head|$.
275 \item[level] The number of less specific superclasses in this class's
276 chain. If @|$c$@->cls.link| is null then @|$c$@->cls.level| is zero;
277 otherwise $@|$c$@->cls.level| = @|$c$@->cls.link@->cls.level| + 1$.
279 \item[n_chains] The number of chains formed by the class's superclasses.
281 \item[chains] A pointer to an array of @|struct sod_chain| structures (see
282 below) describing the class's superclass chains, in decreasing order of
283 specificity of their most specific classes. It is always the case that
284 $@|$c$@->cls.chains[0].classes[$c$@->cls.level]| = c$.
286 \item[off_islots] The offset of the class's @|islots| structure relative to
287 its containing @|ichain| structure. The class doesn't define any slots
288 if and only if this is zero. (The offset can't be zero because the
289 vtable pointer is at offset zero.)
291 \item[islotsz] The size required to store the class's direct slots, i.e.,
292 the size of its @|islots| structure. The class doesn't define any slots
293 if and only if this is zero.
298 \begin{describe}{type}[struct sod_chain]
299 {struct sod_chain \{ \\ \ind
301 const SodClass *const *classes; \\
302 size_t off_ichain; \\
303 const struct sod_vtable *vt; \\
304 size_t ichainsz; \-\\
307 The @|struct sod_chain| structure describes an individual chain of
308 superclasses. It has the following members.
309 \begin{description} \let\makelabel\code
311 \item[n_classes] The number of classes in the chain. This is always at
314 \item[classes] A pointer to an array of class pointers listing the classes
315 in the chain from least- to most-specific. So
316 $@|@<classes>[$i$]@->cls.head| = @|@<classes>[0]|$ for all $0 \le i <
317 @<n_classes>$, @|@<classes>[0]@->cls.link| is always null, and
318 $@|@<classes>[$i$]@->cls.link| = @|@<classes>[$i - 1$]|$ if $1 \le i <
321 \item[off_ichain] The size of the @|ichain| structure for this chain.
323 \item[vt] The vtable for this chain. (It is possible, therefore, to
324 partially duplicate the behaviour of the @<imprint> function by walking
325 the chain structure.\footnote{%
326 There isn't enough information readily available to fill in the class
327 pointers correctly.} %
328 The @<imprint> function is much faster, though.)
330 \item[ichainsz] The size of the @|ichain| structure for this chain.
335 %%%--------------------------------------------------------------------------
336 \section{Class and vtable layout} \label{sec:structures.layout}
338 The layout algorithms for Sod instances and vtables are nontrivial. They are
339 defined here in full detail, since they're effectively fixed by Sod's ABI
340 compatibility guarantees, so they might as well be documented for the sake of
341 interoperating programs.
343 Unfortunately, the descriptions are rather complicated, and, for the most
344 part not necessary to a working understanding of Sod. The skeleton structure
345 definitions shown should be more than enough for readers attempting to make
346 sense of the generated headers and tables.
348 In the description that follows, uppercase letters vary over class names,
349 while the corresponding lowercase letters indicate the class nicknames.
350 Throughout, we consider a class $C$ (therefore with nickname $c$).
353 \subsection{Generic instance structure}
354 \label{sec:structures.layout.instance}
356 The entire state of an instance of $C$ is contained in a single structure of
357 type @|struct $C$__ilayout|.
360 struct $C$__ilayout \{ \\ \ind
361 union $C$__ichainu_$h$ \{ \\ \ind
362 struct $C$__ichain_$h$ \{ \\ \ind
363 const struct $C$__vt_$h$ *_vt; \\
364 struct $H$__islots $h$; \\
366 struct $C$__islots \{ \\ \ind
367 @<type>_1 @<slot>_1; \\
369 @<type>_n @<slot>_n; \-\\
372 struct $A$__ichain_$h$ $a$; \\
375 union $B$__ichainu_$i$ $i$; \\
379 typedef struct $C$__ichain_$h$ $C$;
382 The set of superclasses of $C$, including itself, can be partitioned into
383 chains by following their distinguished superclass links. (Formally, the
384 chains are the equivalence classes determined by the reflexive, symmetric,
385 transitive closure of the `links to' relation.) Chains are identified by
386 naming their least specific classes; the least specific class in a chain is
387 called the \emph{chain head}. Suppose that the chain head of the chain
388 containing $C$ itself is named $H$ (though keep in mind that it's possible
389 that $H$ is in fact $C$ itself.)
391 \subsubsection{The ilayout structure}
392 The @|ilayout| structure contains one member for each of $C$'s superclass
393 chains. The first such member is
395 union $C$__ichainu_$h$ $h$;
397 described below; this is followed by members
399 union $B$__ichainu_$i$ $i$;
401 for each other chain, where $I$ is the head and $B$ the tail (most-specific)
402 class of the chain. The members are in decreasing order of the specificity
403 of the chains' most-specific classes. (Note that all but the first of these
404 unions has already been defined as part of the definition of the
407 \subsubsection{The ichainu union}
408 The @|ichainu| union contains a member for each class in the chain. The
411 struct $C$__ichain_$h$ $c$;
413 and this is followed by corresponding members
415 struct $A$__ichain_$h$ $a$;
417 for each of $C$'s superclasses $A$ in the same chain in some (unimportant)
418 order. The (somewhat obtuse) purpose of this union is to engage the `common
419 initial sequence' rule of \cite[6.5.2.3]{ISO:1990:IIP,ANSI:1999:AII}.
421 \subsubsection{The ichain structure}
422 The @|ichain| structure contains (in order), a pointer
424 const struct $C$__vt_$h$ *_vt;
426 followed by a structure
428 struct $A$__islots $a$;
430 for each superclass $A$ of $C$ in the same chain which defines slots, from
431 least- to most-specific; if $C$ defines any slots, then the last member is
433 struct $C$__islots $c$;
435 A `pointer to $C$' is always assumed (and, indeed, defined in C's
436 type system) to be a pointer to the @|struct $C$__ichain_$h$|.
438 \subsubsection{The islots structure}
439 Finally, the @|islots| structure simply contains one member for each slot
440 defined by $C$ in the order they appear in the class definition.
443 \subsection{Generic vtable structure} \label{sec:structures.layout.vtable}
445 As described above, each @|ichain| structure of an instance's storage has a
448 const struct $C$__vt_$h$ *_vt;
450 In general, the vtables for the different chains will have \emph{different}
453 The instance layout splits neatly into disjoint chains. This is necessary
454 because each @|ichain| must have as a prefix the @|ichain| for each
455 superclass in the same chain, and each slot must be stored in exactly one
456 place. The layout of vtables doesn't have this second requirement: it
457 doesn't matter that there are multiple method entry pointers for the same
458 effective method as long as they all work correctly. Indeed, it's essential
459 that there are multiple entry pointers, because each chain's method entry
460 function will need to apply a different offset to the receiver pointer before
461 invoking the effective method.
463 A vtable for a class $C$ with chain head $H$ has the following general
466 union $C$__vtu_$h$ \{ \\ \ind
467 struct $C$__vt_$h$ \{ \\ \ind
468 const $P$ *_class; \\
471 const $Q$ *_cls_$j$; \\
473 ptrdiff_t _off_$i$; \\
475 struct $C$__vtmsgs_$a$ \{ \\ \ind
476 @<type> (*@<msg>)($C$ *, $\dots$); \\
483 extern const union $C$__vtu_$h$ $C$__vtable_$h$;
486 In the following, let $M$ be the metaclass of $C$.
488 \subsubsection{The vtu union}
489 The outer layer is a @|union $C$__vtu_$h$| containing a member
491 struct $A$__vt_$h$ $a$;
493 for each of $C$'s superclasses $A$ in the same chain, with $C$ itself listed
496 This is mostly an irrelevant detail, whose purpose is to defend against
497 malicious compilers: pointers are always to one of the inner @|vt|
498 structures. It's important only because it's the outer @|vtu| union which is
499 exported by name. Specifically, for each chain of $C$'s superclasses there
500 is an external object
502 const union $A$__vtu_$i$ $C$__vtable_$i$;
504 where $A$ and $I$ are respectively the most and least specific classes in the
507 \subsubsection{The vt structure}
508 The first member in the @|vt| structure is the \emph{root class pointer}
512 Among the superclasses of $C$ there must be exactly one class $O$ which
513 itself has no direct superclasses; this is the \emph{root superclass} of $C$.
514 (This is a rule enforced by the Sod translator.) The metaclass $R$ of $O$ is
515 then the \emph{root metaclass} of $C$. The @|_class| member points to the
516 @|ichain| structure of most specific superclass $P$ of $M$ in the same chain
519 This is followed by the \emph{base offset}
523 which is simply the offset of the @|ichain| structure from the instance base.
525 The rest of the vtable structure is populated by walking the superclass chain
526 containing $C$ as follows. For each such superclass $B$, in increasing order
527 of specificity, walk the class precedence list of $B$, again starting with
528 its least-specific superclass. (This complex procedure guarantees that the
529 vtable structure for a class is a prefix of the vtable structure for any of
530 its subclasses in the same chain.)
532 So, let $A$ be some superclass of $C$ which has been encountered during this
537 \item Let $N$ be the metaclass of $A$. Examine the superclass chains of $N$
538 in order of decreasing specificity of their most-specific classes. Let $J$
539 be the chain head of such a chain. If there is currently no class pointer
540 for the chain headed by $J$, then add a member
544 to the vtable pointing to the appropriate @|islots| structure within $M$'s
545 class object, where $Q$ is the most specific superclass of $M$ in the same
548 \item Examine the superclass chains of $A$ in order of decreasing specificity
549 of their most-specific classes. Let $I$ be the chain head of such a chain.
550 If there is currently no member @|_off_$i$| then add a member
554 to the vtable, containing the (signed) offset from the @|ichain| structure
555 of the chain headed by $h$ to that of the chain headed by $i$ within the
558 \item If class $A$ defines any messages, and there is currently no member
559 $a$, then add a member
561 struct $C$__vtmsgs_$a$ $a$;
563 to the vtable. See below.
567 \subsubsection{The vtmsgs structure}
568 Finally, the @|vtmsgs| structures contain pointers to the effective method
569 entry functions for the messages defined by a superclass. There may be more
570 than one method entry for a message, but all of the entry pointers for a
571 message appear together, and entry pointers for separate messages appear in
572 the order in which the messages are defined. If the receiver class has no
573 applicable primary method for a message then it's usual for the method entry
574 pointer to be null (though, as with a lot of things in Sod, extensions may do
575 something different).
577 For a standard message which takes a fixed number of arguments, defined as
579 @<type>_0 $m$(@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n);
581 there is always a `main' entry point,
583 @<type>_0 $m$($C$ *me, @<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n);
586 For a standard message which takes a variable number of arguments,
589 @<type>_0 $m$(@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n, \dots);
591 or a standard message which takes keyword arguments, defined as
593 @<type>_0 $m$(\=@<type>_1 @<arg>_1,
595 @<type>_n @<arg>_n? \+\\
596 @<type>_{n+1} @<kw>_{n+1} @[= @<dflt>_{n+1}@],
598 @<type>_{n'} @<kw>_{n'} @[= @<dflt>_{n'}@]);
600 two entry points are defined: the usual `main' entry point which accepts a
601 variable number of arguments, and a `valist' entry point which accepts an
602 argument of type @|va_list| in place of the variable portion of the argument
605 @<type>_0 $m$($C$ *me, @<type>_1 @<arg>_1, $\ldots$,
606 @<type>_n @<arg>_n, \dots); \\
607 @<type>_0 $m$__v($C$ *me, @<type>_1 @<arg>_1, $\ldots$,
608 @<type>_n @<arg>_n, va_list sod__ap);
612 \subsection{Additional definitions} \label{sec:structures.layout.additional}
614 In addition to the instance and vtable structures described above, the
615 following definitions are made for each class $C$.
617 For each message $m$ directly defined by $C$ there is a macro definition
619 \#define $C$_$m$(@<me>, $\ldots$) @<me>@->_vt@->$c$.$m$(@<me>, $\ldots$)
621 which makes sending the message $m$ to an instance of (any subclass of) $C$
624 If $m$ takes a variable number of arguments, or keyword arguments, the macro
625 is more complicated and is only available in compilers advertising C99
626 support, but the effect is the same. For each variable-argument message,
627 there is also an additional macro for calling the `valist' entry point.
629 \#define $C$_$m$__v(@<me>, $\ldots$, @<sod__ap>)
630 @<me>@->_vt@->$c$.$m$__v(@<me>, $\ldots$, @<sod__ap>)
633 For each proper superclass $A$ of $C$, there is a macro defined
635 $A$ *$C$__CONV_$a$($C$ *_obj);
637 (named in \emph{upper case}) which converts a (static-type) pointer to $C$ to
638 a pointer to the same actual instance, but statically typed as a pointer to
639 $A$. This is most useful when $A$ is not in the same chain as $C$ since
640 in-chain upcasts are both trivial and rarely needed, but the full set is
641 defined for the sake of completeness.
643 Finally, the class object is defined as
645 extern const struct $R$__ilayout $C$__classobj; \\
646 \#define $C$__class (\&$C$__classobj.$j$.$r$) \\
647 \#define $C$__cls_$k$ (\&$C$__classobj.$k$.$n$) \\
650 The exported symbol @|$C$__classobj| contains the entire class instance.
651 This is usually rather unwieldy. The macro @|$C$__class| is usable as a
652 pointer of type @|const $R$~*|, where $R$ is the root metaclass of $C$, i.e.,
653 the metaclass of the least specific superclass of $C$; usually this is
654 @|const SodClass~*|. For each chain of $C$'s metaclass, a macro
655 @|$C$__cls_$k$| is defined, usable as a pointer of type @|const $N$~*|, where
656 $K$ and $N$ are the chain's head and tail classes (i.e., the least- and
657 most-specific classes in the chain) respectively; this macro is
658 \emph{omitted} if $N = R$, i.e., in the common case where $C$'s metaclass is
659 precisely the root metaclass, since the existing @|$C$__class| macro is
663 %%%----- That's all, folks --------------------------------------------------
667 %%% TeX-master: "sod.tex"