X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/f64eb323a5798e155cc494043f5f750abf50a482..fa388683c9116be05ee1778150fd550fd2366a6e:/doc/structures.tex
diff --git a/doc/structures.tex b/doc/structures.tex
index 3826bdc..c8a0d9c 100644
--- a/doc/structures.tex
+++ b/doc/structures.tex
@@ -46,8 +46,8 @@ Instance chains contain slots and vtable pointers, as described below. All
instances have the basic structure of a @|struct sod_instance|.
\begin{describe}[struct sod_instance]{type}
- {struct sod_instance \{ \\ \ind
- const struct sod_vtable *_vt; \- \\
+ {struct sod_instance \{ \\ \ind
+ const struct sod_vtable *_vt; \-\\
\};}
The basic structure of all instances. Members are as follows.
@@ -58,9 +58,9 @@ instances have the basic structure of a @|struct sod_instance|.
\end{describe}
\begin{describe}[struct sod_vtable]{type}
- {struct sod_vtable \{ \\ \ind
- const SodClass *_class; \\
- size_t _base; \- \\
+ {struct sod_vtable \{ \\ \ind
+ const SodClass *_class; \\
+ size_t _base; \-\\
\};}
A vtable contains static metadata needed for efficient conversions and
@@ -93,34 +93,35 @@ recommended.
\begin{figure}[tbp]
\begin{tabular}{p{10pt}p{10pt}}
\begin{nprog}
- struct SodObject__ilayout \{ \\ \ind
- union \{ \\ \ind
- struct SodObject__ichain_obj \{ \\ \ind
- const struct SodObject__vt_obj *_vt; \- \\
- \} obj; \- \\
- \} obj; \- \\
+ struct SodObject__ilayout \{ \\ \ind
+ union \{ \\ \ind
+ struct SodObject__ichain_obj \{ \\ \ind
+ const struct SodObject__vt_obj *_vt; \-\\
+ \} obj; \-\\
+ \} obj; \-\\
\};
\end{nprog}
&
\begin{nprog}
- struct SodObject__vt_obj \{ \\ \ind
- const SodClass *_class; \\
- size_t _base; \\
- struct SodObject__vtmsgs_obj \{ \\ \ind
- void (*init)(SodObject *me, ...); \\
- void (*init__v)(SodObject *me, va_list); \\
- int (*teardown)(SodObject *me); \- \\
- \} obj; \- \\
+ struct SodObject__vt_obj \{ \\ \ind
+ const SodClass *_class; \\
+ size_t _base; \\
+ struct SodObject__vtmsgs_obj \{ \\ \ind
+ void (*init)(SodObject *me, ...); \\
+ void (*init__v)(SodObject *me, va_list); \\
+ int (*teardown)(SodObject *me); \-\\
+ \} obj; \-\\
\};
- \end{nprog} \\
+ \end{nprog} \\
\end{tabular}
\caption{Instance and vtable layout of @|SodObject|}
\label{fig:structures.root.sodobject}
\end{figure}
\begin{describe}[SodObject]{cls}
- {[nick = obj, metaclass = SodClass, lisp_metaclass = sod_class] \\
- class SodObject \{ \\ \ind
+ {[nick = obj, metaclass = SodClass,
+ lisp_metaclass = sod_class] \\
+ class SodObject \{ \\ \ind
void init(?);
\}}
@@ -199,24 +200,24 @@ recommended.
\subsection{The SodClass class} \label{sec:structures.root.sodclass}
\begin{describe}[SodClass]{cls}
- {[nick = cls, link = SodObject] \\
- class SodClass : SodObject \{ \\ \ind
- const char *name; \\
- const char *nick; \\
- size_t initsz; \\
- size_t align; \\
- void *(*imprint)(void *@); \\
- size_t n_supers; \\
- const SodClass *const *supers; \\
- size_t n_cpl; \\
- const SodClass *const *cpl; \\
- const SodClass *link; \\
- const SodClass *head; \\
- size_t level; \\
- size_t n_chains; \\
- const struct sod_chain *chains; \\
- size_t off_islots; \\
- size_t islotsz; \- \\
+ {[nick = cls, link = SodObject] \\
+ class SodClass : SodObject \{ \\ \ind
+ const char *name; \\
+ const char *nick; \\
+ size_t initsz; \\
+ size_t align; \\
+ void *(*imprint)(void *@
); \\
+ size_t n_supers; \\
+ const SodClass *const *supers; \\
+ size_t n_cpl; \\
+ const SodClass *const *cpl; \\
+ const SodClass *link; \\
+ const SodClass *head; \\
+ size_t level; \\
+ size_t n_chains; \\
+ const struct sod_chain *chains; \\
+ size_t off_islots; \\
+ size_t islotsz; \-\\
\}}
The @|SodClass| class defines no additional messages , but there are a
@@ -289,12 +290,12 @@ recommended.
\end{describe}
\begin{describe}[struct sod_chain]{type}
- {struct sod_chain \{ \\ \ind
- size_t n_classes; \\
- const SodClass *const *classes; \\
- size_t off_ichain; \\
- const struct sod_vtable *vt; \\
- size_t ichainsz; \- \\
+ {struct sod_chain \{ \\ \ind
+ size_t n_classes; \\
+ const SodClass *const *classes; \\
+ size_t off_ichain; \\
+ const struct sod_vtable *vt; \\
+ size_t ichainsz; \-\\
\};}
The @|struct sod_chain| structure describes an individual chain of
@@ -350,25 +351,25 @@ The entire state of an instance of $C$ is contained in a single structure of
type @|struct $C$__ilayout|.
\begin{prog}
- struct $C$__ilayout \{ \\ \ind
- union $C$__ichainu_$h$ \{ \\ \ind
- struct $C$__ichain_$h$ \{ \\ \ind
- const struct $C$__vt_$h$ *_vt; \\
- struct $H$__islots $h$; \\
- \quad$\vdots$ \\
- struct $C$__islots \{ \\ \ind
- @_1 @_1; \\
- \quad$\vdots$ \\
- @_n @_n; \- \\
- \} $c$; \- \\
- \} $c$; \\
- struct $H$__ichain_$h$ $h$; \\
- \quad$\vdots$ \- \\
- \} $h$; \\
- union $B$__ichainu_$i$ $i$; \\
- \quad$\vdots$ \- \\
- \};
- \\+
+ struct $C$__ilayout \{ \\ \ind
+ union $C$__ichainu_$h$ \{ \\ \ind
+ struct $C$__ichain_$h$ \{ \\ \ind
+ const struct $C$__vt_$h$ *_vt; \\
+ struct $H$__islots $h$; \\
+ \quad$\vdots$ \\
+ struct $C$__islots \{ \\ \ind
+ @_1 @_1; \\
+ \quad$\vdots$ \\
+ @_n @_n; \-\\
+ \} $c$; \-\\
+ \} $c$; \\
+ struct $H$__ichain_$h$ $h$; \\
+ \quad$\vdots$ \-\\
+ \} $h$; \\
+ union $B$__ichainu_$i$ $i$; \\
+ \quad$\vdots$ \-\\
+ \}; \\+
+
typedef struct $C$__ichain_$h$ $C$;
\end{prog}
@@ -379,7 +380,7 @@ transitive closure of the `links to' relation.) Chains are identified by
naming their least specific classes; the least specific class in a chain is
called the \emph{chain head}. Suppose that the chain head of the chain
containing $C$ itself is named $H$ (though keep in mind that it's possible
-that .$H$ is in fact $C$ itself.)
+that $H$ is in fact $C$ itself.)
\subsubsection{The ilayout structure}
The @|ilayout| structure contains one member for each of $C$'s superclass
@@ -457,26 +458,28 @@ method.
A vtable for a class $C$ with chain head $H$ has the following general
structure.
\begin{prog}
- union $C$__vtu_$h$ \{ \\ \ind
- struct $C$__vt_$h$ \{ \\ \ind
- const $P$ *_class; \\
- size_t _base; \\
- \quad$\vdots$ \\
- const $Q$ *_cls_$j$; \\
- \quad$\vdots$ \\
- ptrdiff_t _off_$i$; \\
- \quad$\vdots$ \\
- struct $C$__vtmsgs_$a$ \{ \\ \ind
- @ (*@)($C$ *, $\dots$); \\
- \quad$\vdots$ \- \\
- \} $a$; \\
- \quad$\vdots$ \- \\
- \} $c$; \- \\
- \};
- \\+
+ union $C$__vtu_$h$ \{ \\ \ind
+ struct $C$__vt_$h$ \{ \\ \ind
+ const $P$ *_class; \\
+ size_t _base; \\
+ \quad$\vdots$ \\
+ const $Q$ *_cls_$j$; \\
+ \quad$\vdots$ \\
+ ptrdiff_t _off_$i$; \\
+ \quad$\vdots$ \\
+ struct $C$__vtmsgs_$a$ \{ \\ \ind
+ @ (*@)($C$ *, $\dots$); \\
+ \quad$\vdots$ \-\\
+ \} $a$; \\
+ \quad$\vdots$ \-\\
+ \} $c$; \-\\
+ \}; \\+
+
extern const union $C$__vtu_$h$ $C$__vtable_$h$;
\end{prog}
+In the following, let $M$ be the metaclass of $C$.
+
\subsubsection{The vtu union}
The outer layer is a @|union $C$__vtu_$h$| containing a member
\begin{prog}
@@ -485,18 +488,11 @@ The outer layer is a @|union $C$__vtu_$h$| containing a member
for each of $C$'s superclasses $A$ in the same chain, with $C$ itself listed
first.
-This is mostly an irrelevant detail,
-whose purpose is to defend against malicious compilers:
-pointers are always to one of the inner
-@|vt|
-structures.
-It's important only because it's the outer
-@|vtu|
-union which is exported by name.
-Specifically, for each chain of
-$C$'s
-superclasses
-there is an external object
+This is mostly an irrelevant detail, whose purpose is to defend against
+malicious compilers: pointers are always to one of the inner @|vt|
+structures. It's important only because it's the outer @|vtu| union which is
+exported by name. Specifically, for each chain of $C$'s superclasses there is
+an external object
\begin{prog}
const union $A$__vtu_$i$ $C$__vtable_$i$;
\end{prog}
@@ -589,9 +585,12 @@ defined as
\end{prog}
or a standard message which takes keyword arguments, defined as
\begin{prog}
- @_0 $m$(\=@_1 @_1, $\ldots$, @_n @_n? \+ \\
- @_{n+1} @_{n+1} @[= @_{n+1}@], $\ldots$,
- @_m @_m @[= @_m@]);
+ @_0 $m$(\=@_1 @_1,
+ $\ldots$,
+ @_n @_n? \+\\
+ @_{n+1} @_{n+1} @[= @_{n+1}@],
+ $\ldots$,
+ @_m @_m @[= @_m@]);
\end{prog}
two entry points are defined: the usual `main' entry point which accepts a
variable number of arguments, and a `valist' entry point which accepts an
@@ -599,7 +598,7 @@ argument of type @|va_list| in place of the variable portion of the argument
list or keywords.
\begin{prog}
@_0 $m$($C$ *me, @_1 @_1, $\ldots$,
- @_n @_n, \dots); \\
+ @_n @_n, \dots); \\
@_0 $m$__v($C$ *me, @_1 @_1, $\ldots$,
@_n @_n, va_list sod__ap);
\end{prog}
@@ -638,7 +637,7 @@ defined for the sake of completeness.
Finally, the class object is defined as
\begin{prog}
- extern const struct $R$__ilayout $C$__classobj; \\
+ extern const struct $R$__ilayout $C$__classobj; \\
\#define $C$__class (\&$C$__classobj.$j$.$r$)
\end{prog}
The exported symbol @|$C$__classobj| contains the entire class instance.