X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/99fca9a58949436b350c761c31390c80a33af674..00d59354c311fb28730b7c9b117b0d91aac092cc:/doc/concepts.tex?ds=sidebyside

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 67dc35b..8e774fe 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -144,9 +144,9 @@ This partial order is not quite sufficient for our purposes.  For each class
 $C$, we shall need to extend it into a total order on $C$'s superclasses.
 This calculation is called \emph{superclass linearization}, and the result is
 a \emph{class precedence list}, which lists each of $C$'s superclasses
-exactly once.  If a superclass $B$ precedes (resp.\ follows) some other
-superclass $A$ in $C$'s class precedence list, then we say that $B$ is a more
-(resp.\ less) \emph{specific} superclass of $C$ than $A$ is.
+exactly once.  If a superclass $B$ precedes or follows some other superclass
+$A$ in $C$'s class precedence list, then we say that $B$ is respectively a
+more or less \emph{specific} superclass of $C$ than $A$.
 
 The superclass linearization algorithm isn't fixed, and extensions to the
 translator can introduce new linearizations for special effects, but the
@@ -159,8 +159,8 @@ following properties are expected to hold.
   list, i.e., $B$ is a more specific superclass of $C$ than $A$ is.
 \end{itemize}
 The default linearization algorithm used in Sod is the \emph{C3} algorithm,
-which has a number of good properties described in~\cite{Barrett:1996:MSL}.
-It works as follows.
+which has a number of good properties described
+in~\cite{barrett-1996:monot-super-linear-dylan}.  It works as follows.
 \begin{itemize}
 \item A \emph{merge} of some number of input lists is a single list
   containing each item that is in any of the input lists exactly once, and no
@@ -263,8 +263,9 @@ It works as follows.
 
   \end{itemize}
 
-  (This example combines elements from \cite{Barrett:1996:MSL} and
-  \cite{Ducournau:1994:PMM}.)
+  (This example combines elements from
+  \cite{barrett-1996:monot-super-linear-dylan} and
+  \cite{ducournau-1994:monot-multip-inher-linear}.)
 \end{example}
 
 \subsubsection{Class links and chains}
@@ -473,12 +474,12 @@ There are three main cases to distinguish.
   a lookup at runtime to find the appropriate offset by which to adjust the
   pointer.  The conversion can be performed using the appropriate generated
   upcast macro (see below); the general case is handled by the macro
-  \descref{SOD_XCHAIN}{mac}.
+  \descref{mac}{SOD_XCHAIN}.
 \item If $B$ is a subclass of~$C$ then the conversion is a \emph{downcast};
   otherwise the conversion is a~\emph{cross-cast}.  In either case, the
   conversion can fail: the object in question might not be an instance of~$B$
-  after all.  The macro \descref{SOD_CONVERT}{mac} and the function
-  \descref{sod_convert}{fun} perform general conversions.  They return a null
+  after all.  The macro \descref{mac}{SOD_CONVERT} and the function
+  \descref{fun}{sod_convert} perform general conversions.  They return a null
   pointer if the conversion fails.  (These are therefore your analogue to the
   \Cplusplus\ @|dynamic_cast<>| operator.)
 \end{itemize}
@@ -607,9 +608,9 @@ message.  The method combination determines which direct method rÃ´les are
 acceptable, and, for each rÃ´le, the appropriate argument lists and return
 types.
 
-One direct method, $M$, is said to be more (resp.\ less) \emph{specific} than
+One direct method, $M$, is said to be more or less \emph{specific} than
 another, $N$, with respect to a receiving class~$C$, if the class defining
-$M$ is a more (resp.\ less) specific superclass of~$C$ than the class
+$M$ is respectively a more or less specific superclass of~$C$ than the class
 defining $N$.
 
 \subsubsection{The standard method combination}
@@ -695,7 +696,7 @@ entry functions.
       node [above right = 0mm and -8mm]
       {$\vcenter{\hbox{\Huge\textcolor{red}{!}}}
         \vcenter{\hbox{\begin{tabular}[c]{l}
-                         \textsf{next_method} \\
+                         @|next_method| \\
                          pointer is null
                        \end{tabular}}}$};
 
@@ -820,7 +821,7 @@ The aggregating method combinations provided are as follows.
 \item[progn] The message must return @|void|.  The applicable primary methods
   are simply invoked in turn, most specific first.
 \item[sum] The message must return a numeric type.\footnote{%
-    The Sod translator does not check this, since it doesn't have enough
+    The Sod translator doesn't check this, since it doesn't have enough
     insight into @|typedef| names.} %
   The applicable primary methods are invoked in turn, and their return values
   added up.  The final result is the sum of the individual values.
@@ -924,14 +925,14 @@ Construction of a new instance of a class involves three steps.
   instance's slots, and maybe links it into any external data structures as
   necessary.
 \end{enumerate}
-The \descref{SOD_DECL}[macro]{mac} handles constructing instances with
+The \descref{mac}{SOD_DECL}[macro] handles constructing instances with
 automatic storage duration (`on the stack').  Similarly, the
-\descref{SOD_MAKE}[macro]{mac} and the \descref{sod_make}{fun} and
-\descref{sod_makev}{fun} functions construct instances allocated from the
+\descref{mac}{SOD_MAKE}[macro] and the \descref*{fun}{sod_make} and
+\descref{fun}{sod_makev} functions construct instances allocated from the
 standard @|malloc| heap.  Programmers can add support for other allocation
-strategies by using the \descref{SOD_INIT}[macro]{mac} and the
-\descref{sod_init}{fun} and \descref{sod_initv}{fun} functions, which package
-up imprinting and initialization.
+strategies by using the \descref{mac}{SOD_INIT}[macro] and the
+\descref*{fun}{sod_init} and \descref{fun}{sod_initv} functions, which
+package up imprinting and initialization.
 
 \subsubsection{Allocation}
 Instances of most classes (specifically including those classes defined by
@@ -1044,7 +1045,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
@@ -1065,15 +1067,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.
@@ -1093,9 +1101,9 @@ steps.
 Teardown alone, for objects which require special deallocation, or for which
 deallocation occurs automatically (e.g., instances with automatic storage
 duration, or instances whose storage will be garbage-collected), is performed
-using the \descref{sod_teardown}[function]{fun}.  Destruction of instances
+using the \descref{fun}{sod_teardown}[function].  Destruction of instances
 allocated from the standard @|malloc| heap is done using the
-\descref{sod_destroy}[function]{fun}.
+\descref{fun}{sod_destroy}[function].
 
 \subsubsection{Teardown}
 Details of teardown are necessarily class-specific, but typically it
@@ -1120,7 +1128,7 @@ counting system, as follows.
     [role = around]                                             \\
     int obj.teardown()                                          \\
     \{                                                          \\ \ind
-      if (--\,--me@->ref.nref) return (1);                      \\
+      if (@--me@->ref.nref) return (1);                           \\
       else return (CALL_NEXT_METHOD);                         \-\\
     \}                                                        \-\\
   \}
@@ -1153,7 +1161,7 @@ class.
 The code which makes the decision to destroy an object may often not be aware
 of the object's direct class.  Low-level details of deallocation often
 require the proper base address of the instance's storage, which can be
-determined using the \descref{SOD_INSTBASE}[macro]{mac}.
+determined using the \descref{mac}{SOD_INSTBASE}[macro].
 
 %%%--------------------------------------------------------------------------
 \section{Metaclasses} \label{sec:concepts.metaclasses}
@@ -1259,9 +1267,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}
