X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/62f9852b653ff96c776418da9492ea644e4a23cf..2e2816d37bd3951177967d1cf5ce707b75a539fa:/doc/structures.tex?ds=sidebyside 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 *@
); \\ - void *(*init)(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; \- \\ - \} 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 *@
)] A pointer to a function: given a pointer - @
to at least @ .
-
-\item[void *(*init)(void *@ )] A pointer to a function: given a pointer
- @ to at least @ .
-
-\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 @ ); \\
+ void *(*init)(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 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 @ to at least
+ @ .
+
+ \item[init] A pointer to a function: given a pointer @ to at least
+ @ .
+
+ \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 @