X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/8eb242b160e163a1cfc6e810aeda4788116bba1a..630d9305b266dcf14f216513c461fa9f66e798a3:/doc/concepts.tex

diff --git a/doc/concepts.tex b/doc/concepts.tex
index b9aab2f..6ec27b9 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -314,12 +314,13 @@ qualified by the defining class's nickname.
 As well as defining slot names and types, a class can also associate an
 \emph{initial value} with each slot defined by itself or one of its
 superclasses.  A class $C$ provides an \emph{initialization message} (see
-\xref{sec:concepts.lifecycle.birth}, and \xref{sec:structures.root.sodclass})
-whose methods set the slots of a \emph{direct} instance of the class to the
-correct initial values.  If several of $C$'s superclasses define initializers
-for the same slot then the initializer from the most specific such class is
-used.  If none of $C$'s superclasses define an initializer for some slot then
-that slot will be left uninitialized.
+\xref[\instead{sections}]{sec:concepts.lifecycle.birth}, and
+\ref{sec:structures.root.sodobject}) whose methods set the slots of a
+\emph{direct} instance of the class to the correct initial values.  If
+several of $C$'s superclasses define initializers for the same slot then the
+initializer from the most specific such class is used.  If none of $C$'s
+superclasses define an initializer for some slot then that slot will be left
+uninitialized.
 
 The initializer for a slot with scalar type may be any C expression.  The
 initializer for a slot with aggregate type must contain only constant
@@ -939,7 +940,8 @@ layout of an instance of some class~$C$ is described by the type @|struct
 $C$__ilayout|, and if the relevant class is known at compile time then the
 best way to discover the layout size is with the @|sizeof| operator.  Failing
 that, the size required to hold an instance of $C$ is available in a slot in
-$C$'s class object, as @|$C$__class@->cls.initsz|.
+$C$'s class object, as @|$C$__class@->cls.initsz|.  The necessary alignment,
+in bytes, is provided as @|$C$__class@->cls.align|, should this be necessary.
 
 It is not in general sufficient to declare, or otherwise allocate, an object
 of the class type $C$.  The class type only describes a single chain of the
@@ -955,10 +957,6 @@ instances, so, for example, Sod doesn't make using fancy allocators which
 sometimes move objects around in memory any more difficult than it needs to
 be.
 
-There isn't any way to discover the alignment required for a particular
-class's instances at runtime; it's best to be conservative and assume that
-the platform's strictest alignment requirement applies.
-
 The following simple function correctly allocates and returns space for an
 instance of a class given a pointer to its class object @<cls>.
 \begin{prog}
@@ -1046,7 +1044,8 @@ defines a name, type, and (optionally) a default value for the initarg.
 slot or slot initializer item: the property's value determines the initarg's
 name, while the type is taken from the underlying slot type; slot initargs do
 not have default values.  Both kinds define a \emph{direct initarg} for the
-containing class.
+containing class.  (Note that a slot may have any number of slot initargs;
+and any number of slots may have initargs with the same name.)
 
 Initargs are inherited.  The \emph{applicable} direct initargs for an @|init|
 effective method are those defined by the receiving object's class, and all
@@ -1067,15 +1066,21 @@ definitions influence the initialization of slots.
 The process for deciding how to initialize a particular slot works as
 follows.
 \begin{enumerate}
+
 \item If there are any slot initargs defined on the slot, or any of its slot
   initializers, \emph{and} the sender supplied a value for one or more of the
-  corresponding effective initargs, then the value of the most specific slot
-  initarg is stored in the slot.
+  corresponding effective initargs, then the value of the most specific such
+  initarg is stored in the slot.  (For this purpose, initargs defined earlier
+  in a class definition are more specific than initargs defined later.)
+
 \item Otherwise, if there are any slot initializers defined which include an
   initializer expression, then the initializer expression from the most
   specific such slot initializer is evaluated and its value stored in the
-  slot.
+  slot.  (A class may define at most one initializer for any particular slot,
+  so no further disambiguation is required.)
+
 \item Otherwise, the slot is left uninitialized.
+
 \end{enumerate}
 Note that the default values (if any) of effective initargs do \emph{not}
 affect this procedure.
@@ -1261,9 +1266,35 @@ the minimal $M_j$.
 \subsection{Translation-time metaobjects}
 \label{sec:concepts.metaclasses.compile-time}
 
+Within the translator, modules, classes, slots and initializers, messages and
+methods are all represented as instances of classes.  Since the translator is
+written in Common Lisp, these translation-time metaobject classes are all
+CLOS classes.  Extensions can influence the translator's behaviour -- and
+hence the layout and behaviour of instances at runtime -- by subclassing the
+built-in metaobject classes and implementing methods on appropriate generic
+functions.
 
-
-\fixme{unwritten}
+Metaobject classes are chosen in a fairly standard way.
+\begin{itemize}
+\item All metaobject definitions support a symbol-valued property, usually
+  named @|@<thing>_class| (e.g., @|slot_class|, @|method_class|), which sets
+  the metaobject class explicitly.  (The class for a class metaobject is
+  taken from the @|lisp_class| property, because @|class_class| seems less
+  meaningful.)
+\item Failing that, the metaobject's parents choose a default metaobject
+  class, based on the new metaobject's properties; i.e., slots and messages
+  have their metaobject classes chosen by the defining class metaobject;
+  initializer and initarg classes are chosen by the defining class metaobject
+  and the direct slot metaobject; and method classes are chosen by the
+  defining class metaobject and the message metaobject.
+\item Classes have no parents; instead, the default is simply to use the
+  builtin metaobject class @|sod-class|.
+\item Modules are a special case because the property syntax is rather
+  awkward.  All modules are initially created as instances of the built-in
+  metaclass @|module|.  Once the module has been parsed completely, the
+  module metaobject's classes is changed, using @|change-class|, to the class
+  specified in the module's property set.
+\end{itemize}
 
 %%%--------------------------------------------------------------------------
 \section{Compatibility considerations} \label{sec:concepts.compatibility}
