X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/62f9852b653ff96c776418da9492ea644e4a23cf..2e2816d37bd3951177967d1cf5ce707b75a539fa:/doc/structures.tex

diff --git a/doc/structures.tex b/doc/structures.tex
index 029f34c..561075b 100644
--- a/doc/structures.tex
+++ b/doc/structures.tex
@@ -43,23 +43,37 @@ As described below, a pointer to an instance actually points to an
 structure.
 
 Instance chains contain slots and vtable pointers, as described below.  All
-instances have the basic structure of a @|struct sod_instance|, which has the
-following member.
-\begin{description} \let\makelabel\code
-\item[const struct sod_vtable *_vt] A pointer to a \emph{vtable}, which has
-  the basic structure of a @|struct sod_vtable|, described below.
-\end{description}
-
-A vtable contains static metadata needed for efficient conversions and
-message dispatch, and pointers to the instance's class.  Each chain points to
-a different vtable.  All vtables have the basic structure of a @|struct
-sod_vtable|, which has the following members.
-\begin{description} \let\makelabel\code
-\item[const SodClass *_class] A pointer to the instance's class object.
-\item[size_t _base] The offset of this chain structure above the start of the
-  overall instance layout, in bytes.  Subtracting @|_base| from the instance
-  chain pointer finds the layout base address.
-\end{description}
+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; \- \\
+     \};}
+
+  The basic structure of all instances.  Members are as follows.
+  \begin{description} \let\makelabel\code
+  \item[_vt] A pointer to a \emph{vtable}, which has the basic structure of a
+    @|struct sod_vtable|, described below.
+  \end{description}
+\end{describe}
+
+\begin{describe}[struct sod_vtable]{type}
+    {struct sod_vtable \{ \\ \ind
+       const SodClass *_class; \\
+       size_t _base; \- \\
+     \};}
+
+  A vtable contains static metadata needed for efficient conversions and
+  message dispatch, and pointers to the instance's class.  Each chain points
+  to a different vtable.  All vtables have the basic structure of a @|struct
+  sod_vtable|, which has the following members.
+  \begin{description} \let\makelabel\code
+  \item[_class] A pointer to the instance's class object.
+  \item[_base] The offset of this chain structure above the start of the
+    overall instance layout, in bytes.  Subtracting @|_base| from the
+    instance chain pointer finds the layout base address.
+  \end{description}
+\end{describe}
 
 %%%--------------------------------------------------------------------------
 \section{Built-in root objects} \label{sec:structures.root}
@@ -75,168 +89,178 @@ recommended.
 
 \subsection{The SodObject class} \label{sec:structures.root.sodobject}
 
-\begin{prog}
-  struct SodObject__vt_obj \{ \\ \ind
-    const SodClass *_class; \\
-    size_t _base; \- \\
-  \};
-  \\[\bigskipamount]
-  struct SodObject__ilayout \{ \\ \ind
-    union \{ \\ \ind
-      struct SodObject__ichain_obj \{ \\ \ind
-        const struct SodObject__vt_obj *_vt; \- \\
-      \}; \- \\
-    \} obj; \- \\
-  \};
-\end{prog}
-
-The @|SodObject| class defines no slots or messages.  Because @|SodObject|
-has no direct superclasses, there is only one chain, and no inherited slots
-or messages, so the single chain contains only a vtable pointer.
-
-Since there are no messages, and @|SodClass| also has only one chain, the
-vtable contains only the standard class pointer and offset-to-base members.
-In a direct instance of @|SodObject| (why would you want one?)  the class
-pointer contains the address of @|SodObject__class| and the offset is zero.
+\begin{figure}[tbp]
+  \begin{tabular}{p{10pt}p{10pt}}
+    \begin{prog}
+      struct SodObject__ilayout \{ \\ \ind
+        union \{ \\ \ind
+          struct SodObject__ichain_obj \{ \\ \ind
+            const struct SodObject__vt_obj *_vt; \- \\
+          \}; \- \\
+        \} obj; \- \\
+      \};
+    \end{prog}
+    &
+    \begin{prog}
+      struct SodObject__vt_obj \{ \\ \ind
+        const SodClass *_class; \\
+        size_t _base; \- \\
+      \};
+    \end{prog} \\
+  \end{tabular}
+  \caption{Instance and vtable layout of @|SodObject|}
+  \label{fig:structures.root.sodobject}
+\end{figure}
+
+\begin{describe}[SodObject]{cls}
+    {[metaclass = SodClass, lisp_metaclass = sod_class] \\
+     class SodObject \{ \}}
+
+  The @|SodObject| class defines no slots or messages.  Because @|SodObject|
+  has no direct superclasses, there is only one chain, and no inherited
+  slots or messages, so the single chain contains only a vtable pointer.
+
+  Since there are no messages, and @|SodClass| also has only one chain, the
+  vtable contains only the standard class pointer and offset-to-base members.
+  In a direct instance of @|SodObject| (why would you want one?)  the class
+  pointer contains the address of @|SodObject__class| and the offset is zero.
+
+  The instance and vtable layout of @|SodObject| is shown in
+  \xref{fig:structures.root.sodobject}.
+\end{describe}
 
 \subsection{The SodClass class} \label{sec:structures.root.sodclass}
 
-\begin{prog}
-  struct SodClass__vt_obj \{ \\ \ind
-    const SodClass *_class; \\
-    size_t _base; \- \\
-  \};
-  \\[\bigskipamount]
-  struct SodObject__ilayout \{ \\ \ind
-    union \{ \\ \ind
-      struct SodClass__ichain_obj \{ \\ \ind
-        const struct SodClass__vt_obj *_vt; \\
-        struct SodClass__islots \{ \\ \ind
-          const char *name; \\
-          const char *nick; \\
-          size_t initsz; \\
-          void *(*imprint)(void *@<p>); \\
-          void *(*init)(void *@<p>); \\
-          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; \- \\
-        \} cls; \- \\
-      \}; \\
-      SodObject obj; \- \\
-    \} obj; \- \\
-  \};
-\end{prog}
-
-The @|SodClass| class defines no messages, but there are a number of slots.
-Its only direct superclass is @|SodObject| and so (like its superclass) its
-vtable is trivial.
-
-The slots defined are as follows.
-\begin{description} \let\makelabel\code
-
-\item[const char *name] A pointer to the class's name.
-
-\item[const char *nick] A pointer to the class's nickname.
-
-\item[size_t initsz] The size in bytes required to store an instance of the
-  class.
-
-\item[void *(*imprint)(void *@<p>)] A pointer to a function: given a pointer
-  @<p> to at least @<initsz> bytes of appropriately aligned memory, `imprint'
-  this memory it so that it becomes a minimally functional instance of the
-  class: all of the vtable and class pointers are properly initialized, but
-  the slots are left untouched.  The function returns its argument @<p>.
-
-\item[void *(*init)(void *@<p>)] A pointer to a function: given a pointer
-  @<p> to at least @<initsz> bytes of appropriately aligned memory,
-  initialize an instance of the class in it: all of the vtable and class
-  pointers are initialized, as are slots for which initializers are defined.
-  Other slots are left untouched.  The function returns its argument @<p>.
-
-\item[size_t n_supers] The number of direct superclasses.  (This is zero
-  exactly in the case of @|SodObject|.)
-
-\item[const SodClass *const *supers] A pointer to an array of @<n_supers>
-  pointers to class objects listing the class's direct superclasses, in the
-  order in which they were listed in the class definition.  If @<n_supers> is
-  zero, then this pointer is null.
-
-\item[size_t n_cpl] The number of superclasses in the class's class
-  precedence list.
-
-\item[const SodClass *const *cpl] A pointer to an array of pointers to class
-  objects listing all of the class's superclasses, from most- to
-  least-specific, starting with the class itself, so $c@->@|cls|.@|cpl|[0] =
-  c$ for all class objects $c$.
-
-\item[const SodClass *link] If the class is a chain head, then this is a null
-  pointer; otherwise it points to the class's distinguished link superclass
-  (which might or might not be a direct superclass).
-
-\item[const SodClass *head] A pointer to the least-specific class in this
-  class's chain; so $c@->@|cls|.@|head|@->@|cls|.@|link|$ is always null, and either
-  $c@->@|cls|.@|link|$ is null (in which case $c@->@|cls|.@|head| = c$) or
-  $c@->@|cls|.@|head| = c@->@|cls|.@|link|@->@|cls|.@|head|$.
-
-\item[size_t level] The number of less specific superclasses in this class's
-  chain.  If $c@->@|cls|.@|link|$ is null then $c@->@|cls|.@|level|$ is zero;
-  otherwise $c@->@|cls|.@|level| = c@->@|cls|.@|link|@->@|cls|.@|level| +
-  1$.
-
-\item[size_t n_chains]
-The number of chains formed by the class's superclasses.
-
-\item[const struct sod_chain *chains] A pointer to an array of @|struct
-  sod_chain| structures (see below) describing the class's superclass chains,
-  in decreasing order of specificity of their most specific classes.  It is
-  always the case that
-  $c@->@|cls|.@|chains|[0].@|classes|[c@->@|cls|.@|level|] = c$.
-
-\item[size_t off_islots] The offset of the class's @|islots| structure
-  relative to its containing @|ichain| structure.  The class doesn't define
-  any slots if and only if this is zero.  (The offset can't be zero because
-  the vtable pointer is at offset zero.)
-
-\item[size_t islotsz] The size required to store the class's direct slots,
-  i.e., the size of its @|islots| structure.  The class doesn't define any
-  slots if and only if this is zero.
-
-\end{description}
-
-The
-@|struct sod_chain|
-structure describes an individual chain of superclasses.
-It has the following members.
-\begin{description} \let\makelabel\code
-
-\item[size_t n_classes] The number of classes in the chain.  This is always
-  at least one.
-
-\item[const SodClass *const *classes] A pointer to an array of class pointers
-  listing the classes in the chain from least- to most-specific.  So
-  $@<classes>[i]@->@|cls|.@|head| = @<classes>[0]$ for all $0 \le i <
-  @<n_classes>$, $@<classes>[0]@->@|cls|.@|link|$ is always null, and
-  $@<classes>[i]@->@|cls|.@|link| = @<classes>[i - 1]$ if $1 \le i <
-  @<n_classes>$.
-
-\item[size_t off_ichain] The size of the @|ichain| structure for this chain.
-
-\item[const struct sod_vtable *vt] The vtable for this chain.  (It is
-  possible, therefore, to duplicate the behaviour of the @<imprint> function
-  by walking the chain structure.  The @<imprint> function is much faster,
-  though.)
-
-\item[size_t ichainsz] The size of the @|ichain| structure for this chain.
-
-\end{description}
+\begin{describe}[SodClass]{cls}
+    {class SodClass : SodObject \{ \\ \ind
+       const char *name; \\
+       const char *nick; \\
+       size_t initsz; \\
+       void *(*imprint)(void *@<p>); \\
+       void *(*init)(void *@<p>); \\
+       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 messages, but there are a number of slots.
+  Its only direct superclass is @|SodObject| and so (like its superclass) its
+  vtable is trivial.
+
+  The slots defined are as follows.
+  \begin{description} \let\makelabel\code
+
+  \item[name] A pointer to the class's name.
+
+  \item[nick] A pointer to the class's nickname.
+
+  \item[initsz] The size in bytes required to store an instance of the class.
+
+  \item[imprint] A pointer to a function: given a pointer @<p> to at least
+    @<initsz> bytes of appropriately aligned memory, `imprint' this memory it
+    so that it becomes a minimally functional instance of the class: all of
+    the vtable and class pointers are properly initialized, but the slots are
+    left untouched.  The function returns its argument @<p>.
+
+  \item[init] A pointer to a function: given a pointer @<p> to at least
+    @<initsz> bytes of appropriately aligned memory, initialize an instance
+    of the class in it: all of the vtable and class pointers are initialized,
+    as are slots for which initializers are defined.  Other slots are left
+    untouched.  The function returns its argument @<p>.
+
+  \item[n_supers] The number of direct superclasses.  (This is zero exactly
+    in the case of @|SodObject|.)
+
+  \item[supers] A pointer to an array of @<n_supers> pointers to class
+    objects listing the class's direct superclasses, in the order in which
+    they were listed in the class definition.  If @<n_supers> is zero, then
+    this pointer is null.
+
+  \item[n_cpl] The number of superclasses in the class's class precedence
+    list.
+
+  \item[cpl] A pointer to an array of pointers to class objects listing all
+    of the class's superclasses, from most- to least-specific, starting with
+    the class itself, so $c@->@|cls|.@|cpl|[0] = c$ for all class objects
+    $c$.
+
+  \item[link] If the class is a chain head, then this is a null pointer;
+    otherwise it points to the class's distinguished link superclass (which
+    might or might not be a direct superclass).
+
+  \item[head] A pointer to the least-specific class in this class's chain; so
+    $c@->@|cls|.@|head|@->@|cls|.@|link|$ is always null, and either
+    $c@->@|cls|.@|link|$ is null (in which case $c@->@|cls|.@|head| = c$) or
+    $c@->@|cls|.@|head| = c@->@|cls|.@|link|@->@|cls|.@|head|$.
+
+  \item[level] The number of less specific superclasses in this class's
+    chain.  If $c@->@|cls|.@|link|$ is null then $c@->@|cls|.@|level|$ is
+    zero; otherwise $c@->@|cls|.@|level| =
+    c@->@|cls|.@|link|@->@|cls|.@|level| + 1$.
+
+  \item[n_chains] The number of chains formed by the class's superclasses.
+
+  \item[chains] A pointer to an array of @|struct sod_chain| structures (see
+    below) describing the class's superclass chains, in decreasing order of
+    specificity of their most specific classes.  It is always the case that
+    $c@->@|cls|.@|chains|[0].@|classes|[c@->@|cls|.@|level|] = c$.
+
+  \item[off_islots] The offset of the class's @|islots| structure relative to
+    its containing @|ichain| structure.  The class doesn't define any slots
+    if and only if this is zero.  (The offset can't be zero because the
+    vtable pointer is at offset zero.)
+
+  \item[islotsz] The size required to store the class's direct slots, i.e.,
+    the size of its @|islots| structure.  The class doesn't define any slots
+    if and only if this is zero.
+
+  \end{description}
+\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; \- \\
+     \};}
+
+   The @|struct sod_chain| structure describes an individual chain of
+   superclasses.  It has the following members.
+   \begin{description} \let\makelabel\code
+
+   \item[n_classes] The number of classes in the chain.  This is always at
+     least one.
+
+   \item[classes] A pointer to an array of class pointers listing the classes
+     in the chain from least- to most-specific.  So
+     $@<classes>[i]@->@|cls|.@|head| = @<classes>[0]$ for all $0 \le i <
+     @<n_classes>$, $@<classes>[0]@->@|cls|.@|link|$ is always null, and
+     $@<classes>[i]@->@|cls|.@|link| = @<classes>[i - 1]$ if $1 \le i <
+     @<n_classes>$.
+
+   \item[off_ichain] The size of the @|ichain| structure for this chain.
+
+   \item[vt] The vtable for this chain.  (It is possible, therefore, to
+     partially duplicate the behaviour of the @<imprint> function by walking
+     the chain structure.\footnote{%
+       There isn't enough information readily available to fill in the class
+       pointers correctly.} %
+     The @<imprint> function is much faster, though.)
+
+   \item[ichainsz] The size of the @|ichain| structure for this chain.
+
+   \end{description}
+ \end{describe}
 
 %%%--------------------------------------------------------------------------
 \section{Class and vtable layout} \label{sec:structures.layout}
