X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/caa6f4b99a79f95d15a6cc1e5b8dd27ea48b4d03..b05636518b4e46caf9e6a689f11742c6a7a24c6b:/doc/concepts.tex?ds=sidebyside

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 8067739..406c002 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -214,13 +214,13 @@ qualified by the defining class's nickname.
 \subsubsection{Slot initializers}
 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
-subclasses.  A class $C$ provides an \emph{initialization function} (see
+subclasses.  A class $C$ provides an \emph{initialization message} (see
 \xref{sec:concepts.lifecycle.birth}, and \xref{sec:structures.root.sodclass})
-which sets 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.
+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
@@ -270,7 +270,7 @@ slots.  If you want to hide implementation details, the best approach is to
 stash them in a dynamically allocated private structure, and leave a pointer
 to it in a slot.  (This will also help preserve binary compatibility, because
 the private structure can grow more members as needed.  See
-\xref{sec:fixme.compatibility} for more details.
+\xref{sec:fixme.compatibility} for more details.)
 
 \subsubsection{Vtables}
 
@@ -291,8 +291,8 @@ doesn't define any messages, so it doesn't have any methods.  In Sod, a class
 slot containing a function pointer is not at all the same thing as a method.)
 
 \subsubsection{Conversions}
-Suppose one has a value of type pointer to class type of some class~$C$, and
-wants to convert it to a pointer to class type of some other class~$B$.
+Suppose one has a value of type pointer-to-class-type for some class~$C$, and
+wants to convert it to a pointer-to-class-type for some other class~$B$.
 There are three main cases to distinguish.
 \begin{itemize}
 \item If $B$ is a superclass of~$C$, in the same chain, then the conversion
@@ -308,13 +308,13 @@ There are three main cases to distinguish.
   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}.
-\item If $B$ is a subclass of~$C$ then the conversion is an \emph{upcast};
+\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$
-  at all.  The macro \descref{SOD_CONVERT}{mac} and the function
+  after all.  The macro \descref{SOD_CONVERT}{mac} and the function
   \descref{sod_convert}{fun} perform general conversions.  They return a null
   pointer if the conversion fails.  (There are therefore your analogue to the
-  \Cplusplus @|dynamic_cast<>| operator.)
+  \Cplusplus\ @|dynamic_cast<>| operator.)
 \end{itemize}
 The Sod translator generates macros for performing both in-chain and
 cross-chain upcasts.  For each class~$C$, and each proper superclass~$B$
@@ -371,7 +371,7 @@ Keyword arguments can be provided in three ways.
 
 Keyword arguments are provided as a general feature for C functions.
 However, Sod has special support for messages which accept keyword arguments
-(\xref{sec:concepts.methods.keywords}); and they play an essential role in
+(\xref{sec:concepts.methods.keywords}); and they play an essential rÃ´le in
 the instance construction protocol (\xref{sec:concepts.lifecycle.birth}).
 
 %%%--------------------------------------------------------------------------
@@ -407,12 +407,12 @@ A class definition may include \emph{direct methods} for messages defined by
 it or any of its superclasses.
 
 Like messages, direct methods define argument lists and return types, but
-they may also have a \emph{body}, and a \emph{role}.
+they may also have a \emph{body}, and a \emph{rÃ´le}.
 
 A direct method need not have the same argument list or return type as its
 message.  The acceptable argument lists and return types for a method depend
 on the message, in particular its method combination
-(\xref{sec:concepts.methods.combination}), and the method's role.
+(\xref{sec:concepts.methods.combination}), and the method's rÃ´le.
 
 A direct method body is a block of C code, and the Sod translator usually
 defines, for each direct method, a function with external linkage, whose body
@@ -430,8 +430,8 @@ the object's class and its superclasses.  These direct methods are combined
 together to form the \emph{effective method} for that particular class and
 message.  Direct methods can be combined into an effective method in
 different ways, according to the \emph{method combination} specified by the
-message.  The method combination determines which direct method roles are
-acceptable, and, for each role, the appropriate argument lists and return
+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
@@ -442,7 +442,7 @@ defining $N$.
 \subsubsection{The standard method combination}
 The default method combination is called the \emph{standard method
 combination}; other method combinations are useful occasionally for special
-effects.  The standard method combination accepts four direct method roles,
+effects.  The standard method combination accepts four direct method rÃ´les,
 called `primary' (the default), @|before|, @|after|, and @|around|.
 
 All direct methods subject to the standard method combination must have
@@ -461,11 +461,99 @@ If there are no applicable primary methods then no effective method is
 constructed: the vtables contain null pointers in place of pointers to method
 entry functions.
 
+\begin{figure}
+  \begin{tikzpicture}
+    [>=stealth, thick,
+     order/.append style={color=green!70!black},
+     code/.append style={font=\sffamily},
+     action/.append style={font=\itshape},
+     method/.append style={rectangle, draw=black, thin, fill=blue!30,
+                           text height=\ht\strutbox, text depth=\dp\strutbox,
+                           minimum width=40mm}]
+
+    \def\delgstack#1#2#3{
+      \node (#10) [method, #2] {#3};
+      \node (#11) [method, above=6mm of #10] {#3};
+      \draw [->] ($(#10.north)!.5!(#10.north west) + (0mm, 1mm)$) --
+                 ++(0mm, 4mm)
+        node [code, left=4pt, midway] {next_method};
+      \draw [<-] ($(#10.north)!.5!(#10.north east) + (0mm, 1mm)$) --
+                 ++(0mm, 4mm)
+        node [action, right=4pt, midway] {return};
+      \draw [->] ($(#11.north)!.5!(#11.north west) + (0mm, 1mm)$) --
+                 ++(0mm, 4mm)
+        node [code, left=4pt, midway] {next_method}
+        node (ld) [above] {$\smash\vdots\mathstrut$};
+      \draw [<-] ($(#11.north)!.5!(#11.north east) + (0mm, 1mm)$) --
+                 ++(0mm, 4mm)
+        node [action, right=4pt, midway] {return}
+        node (rd) [above] {$\smash\vdots\mathstrut$};
+      \draw [->] ($(ld.north) + (0mm, 1mm)$) -- ++(0mm, 4mm)
+        node [code, left=4pt, midway] {next_method};
+      \draw [<-] ($(rd.north) + (0mm, 1mm)$) -- ++(0mm, 4mm)
+        node [action, right=4pt, midway] {return};
+      \node (p) at ($(ld.north)!.5!(rd.north)$) {};
+      \node (#1n) [method, above=5mm of p] {#3};
+      \draw [->, order] ($(#10.south east) + (4mm, 1mm)$) --
+                          ($(#1n.north east) + (4mm, -1mm)$)
+        node [midway, right, align=left]
+        {Most to \\ least \\ specific};}
+
+    \delgstack{a}{}{@|around| method}
+    \draw [<-] ($(a0.south)!.5!(a0.south west) - (0mm, 1mm)$) --
+               ++(0mm, -4mm);
+    \draw [->] ($(a0.south)!.5!(a0.south east) - (0mm, 1mm)$) --
+               ++(0mm, -4mm)
+      node [action, right=4pt, midway] {return};
+
+    \draw [->] ($(an.north)!.6!(an.north west) + (0mm, 1mm)$) --
+               ++(-8mm, 8mm)
+      node [code, midway, left=3mm] {next_method}
+      node (b0) [method, above left = 1mm + 4mm and -6mm - 4mm] {};
+    \node (b1) [method] at ($(b0) - (2mm, 2mm)$) {};
+    \node (bn) [method] at ($(b1) - (2mm, 2mm)$) {@|before| method};
+    \draw [->, order] ($(bn.west) - (6mm, 0mm)$) -- ++(12mm, 12mm)
+      node [midway, above left, align=center] {Most to \\ least \\ specific};
+    \draw [->] ($(b0.north east) + (-10mm, 1mm)$) -- ++(8mm, 8mm)
+      node (p) {};
+
+    \delgstack{m}{above right=1mm and 0mm of an.west |- p}{Primary method}
+    \draw [->] ($(mn.north)!.5!(mn.north west) + (0mm, 1mm)$) -- ++(0mm, 4mm)
+      node [code, left=4pt, midway] {next_method}
+      node [above right = 0mm and -8mm]
+      {$\vcenter{\hbox{\Huge\textcolor{red}{!}}}
+        \vcenter{\hbox{\begin{tabular}[c]{l}
+                         \textsf{next_method} \\
+                         pointer is null
+                       \end{tabular}}}$};
+
+    \draw [->, color=blue, dotted]
+        ($(m0.south)!.2!(m0.south east) - (0mm, 1mm)$) --
+        ($(an.north)!.2!(an.north east) + (0mm, 1mm)$)
+      node [midway, sloped, below] {Return value};
+
+    \draw [<-] ($(an.north)!.6!(an.north east) + (0mm, 1mm)$) --
+               ++(8mm, 8mm)
+      node [action, midway, right=3mm] {return}
+      node (f0) [method, above right = 1mm and -6mm] {};
+    \node (f1) [method] at ($(f0) + (-2mm, 2mm)$) {};
+    \node (fn) [method] at ($(f1) + (-2mm, 2mm)$) {@|after| method};
+    \draw [<-, order] ($(f0.east) + (6mm, 0mm)$) -- ++(-12mm, 12mm)
+      node [midway, above right, align=center]
+      {Least to \\ most \\ specific};
+    \draw [<-] ($(fn.north west) + (6mm, 1mm)$) -- ++(-8mm, 8mm);
+
+  \end{tikzpicture}
+
+  \caption{The standard method combination}
+  \label{fig:concepts.methods.stdmeth}
+\end{figure}
+
 The effective method for a message with standard method combination works as
-follows.
+follows (see also~\xref{fig:concepts.methods.stdmeth}).
 \begin{enumerate}
 
-\item If any applicable methods have the @|around| role, then the most
+\item If any applicable methods have the @|around| rÃ´le, then the most
   specific such method, with respect to the class of the receiving object, is
   invoked.
 
@@ -475,21 +563,21 @@ follows.
 
   If there any remaining @|around| methods, then @|next_method| invokes the
   next most specific such method, returning whichever value that method
-  returns; otherwise the behaviour of @|next_method| is to invoke the before
-  methods (if any), followed by the most specific primary method, followed by
-  the @|around| methods (if any), and to return whichever value was returned
-  by the most specific primary method, as described in the following items.
-  That is, the behaviour of the least specific @|around| method's
-  @|next_method| function is exactly the behaviour that the effective method
-  would have if there were no @|around| methods.  Note that if the
-  least-specific @|around| method calls its @|next_method| more than once
-  then the whole sequence of @|before|, primary, and @|after| methods occurs
-  multiple times.
+  returns; otherwise the behaviour of @|next_method| is to invoke the
+  @|before| methods (if any), followed by the most specific primary method,
+  followed by the @|after| methods (if any), and to return whichever value
+  was returned by the most specific primary method, as described in the
+  following items.  That is, the behaviour of the least specific @|around|
+  method's @|next_method| function is exactly the behaviour that the
+  effective method would have if there were no @|around| methods.  Note that
+  if the least-specific @|around| method calls its @|next_method| more than
+  once then the whole sequence of @|before|, primary, and @|after| methods
+  occurs multiple times.
 
   The value returned by the most specific @|around| method is the value
   returned by the effective method.
 
-\item If any applicable methods have the @|before| role, then they are all
+\item If any applicable methods have the @|before| rÃ´le, then they are all
   invoked, starting with the most specific.
 
 \item The most specific applicable primary method is invoked.
@@ -510,7 +598,7 @@ follows.
   returned to the least specific @|around| method, which called it via its
   own @|next_method| function.
 
-\item If any applicable methods have the @|after| role, then they are all
+\item If any applicable methods have the @|after| rÃ´le, then they are all
   invoked, starting with the \emph{least} specific.  (Hence, the most
   specific @|after| method is invoked with the most `afterness'.)
 
@@ -521,7 +609,7 @@ dynamic environment appropriately for the primary methods of its subclasses,
 e.g., by claiming a lock, and restore it afterwards.
 
 The @|next_method| function provided to methods with the primary and
-@|around| roles accepts the same arguments, and returns the same type, as the
+@|around| rÃ´les accepts the same arguments, and returns the same type, as the
 message, except that one or two additional arguments are inserted at the
 front of the argument list.  The first additional argument is always the
 receiving object, @|me|.  If the message accepts a variable argument suffix,
@@ -531,7 +619,7 @@ second additional argument; otherwise, In the former case, a variable
 of the argument pointer (so the method body can process the variable argument
 suffix itself, and still pass a fresh copy on to the next method).
 
-A method with the primary or @|around| role may use the convenience macro
+A method with the primary or @|around| rÃ´le may use the convenience macro
 @|CALL_NEXT_METHOD|, which takes no arguments itself, and simply calls
 @|next_method| with appropriate arguments: the receiver @|me| pointer, the
 argument pointer @|sod__master_ap| (if applicable), and the method's
@@ -551,7 +639,7 @@ specific primary method, as the standard method combination does, they invoke
 the applicable primary methods in turn and aggregate the return values from
 each.
 
-The aggregating method combinations accept the same four roles as the
+The aggregating method combinations accept the same four rÃ´les as the
 standard method combination, and @|around|, @|before|, and @|after| methods
 work in the same way.
 
@@ -741,7 +829,11 @@ environment in which it operates.
 
 Details of initialization are necessarily class-specific, but typically it
 involves setting the instance's slots to appropriate values, and possibly
-linking it into some larger data structure to keep track of it.
+linking it into some larger data structure to keep track of it.  It is
+possible for initialization methods to attempt to allocate resources, but
+this must be done carefully: there is currently no way to report an error
+from object initialization, so the object must be marked as incompletely
+initialized, and left in a state where it will be safe to tear down later.
 
 Initialization is performed by sending the imprinted instance an @|init|
 message, defined by the @|SodObject| class.  This message uses a nonstandard
@@ -765,7 +857,7 @@ be executed to set up a new instance.  Each superclass's initialization
 fragments are executed with @|me| bound to an instance pointer of the
 appropriate superclass type, immediately after that superclass's slots (if
 any) have been initialized; therefore, fragments defined by a more specific
-superclass are executed after fragments defined by a more specific
+superclass are executed after fragments defined by a less specific
 superclass.  A class may define more than one initialization fragment: the
 fragments are executed in the order in which they appear in the class
 definition.  It is possible for an initialization fragment to use @|return|
@@ -840,9 +932,9 @@ allocated from the standard @|malloc| heap is done using the
 \descref{sod_destroy}[function]{fun}.
 
 \subsubsection{Teardown}
-Details of initialization are necessarily class-specific, but typically it
-involves setting the instance's slots to appropriate values, and possibly
-linking it into some larger data structure to keep track of it.
+Details of teardown are necessarily class-specific, but typically it
+involves releasing resources held by the instance, and disentangling it from
+any data structures it might be linked into.
 
 Teardown is performed by sending the instance the @|teardown| message,
 defined by the @|SodObject| class.  The message returns an integer, used as a
@@ -856,7 +948,7 @@ This simple protocol can be used, for example, to implement a reference
 counting system, as follows.
 \begin{prog}
   [nick = ref]                                                  \\
-  class ReferenceCountedObject \{                               \\ \ind
+  class ReferenceCountedObject: SodObject \{                    \\ \ind
     unsigned nref = 1;                                          \\-
     void inc() \{ me@->ref.nref++; \}                           \\-
     [role = around]                                             \\
@@ -868,18 +960,18 @@ counting system, as follows.
   \}
 \end{prog}
 
-This message uses a nonstandard method combination which works like the
-standard combination, except that the \emph{default behaviour}, if there is
-no overriding method, is to execute the superclass's teardown fragments, and
-to return zero.  This default behaviour may be invoked multiple times if some
-method calls on its @|next_method| more than once, unless some other method
-takes steps to prevent this.
+The @|teardown| message uses a nonstandard method combination which works
+like the standard combination, except that the \emph{default behaviour}, if
+there is no overriding method, is to execute the superclass's teardown
+fragments, and to return zero.  This default behaviour may be invoked
+multiple times if some method calls on its @|next_method| more than once,
+unless some other method takes steps to prevent this.
 
 A class can define \emph{teardown fragments}: pieces of literal code to be
 executed to shut down an instance.  Each superclass's teardown fragments are
 executed with @|me| bound to an instance pointer of the appropriate
 superclass type; fragments defined by a more specific superclass are executed
-before fragments defined by a more specific superclass.  A class may define
+before fragments defined by a less specific superclass.  A class may define
 more than one teardown fragment: the fragments are executed in the order in
 which they appear in the class definition.  It is possible for an
 initialization fragment to use @|return| or @|goto| for special control-flow
