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}).
%%%--------------------------------------------------------------------------
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
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
\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
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.
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.
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'.)
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,
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
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.
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
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|
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] \\
\}
\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
~mdw / sod / blobdiff