X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/13cb243aea114b87d4382b8aaf1d357c9495dc0e..b05636518b4e46caf9e6a689f11742c6a7a24c6b:/doc/concepts.tex diff --git a/doc/concepts.tex b/doc/concepts.tex index 0f4b336..406c002 100644 --- a/doc/concepts.tex +++ b/doc/concepts.tex @@ -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 @@ -499,7 +499,7 @@ entry functions. node [midway, right, align=left] {Most to \\ least \\ specific};} - \delgstack{a}{}{Around method} + \delgstack{a}{}{@|around| method} \draw [<-] ($(a0.south)!.5!(a0.south west) - (0mm, 1mm)$) -- ++(0mm, -4mm); \draw [->] ($(a0.south)!.5!(a0.south east) - (0mm, 1mm)$) -- @@ -511,7 +511,7 @@ entry functions. 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}; + \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) @@ -537,7 +537,7 @@ entry functions. 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}; + \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}; @@ -553,7 +553,7 @@ The effective method for a message with standard method combination works as 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. @@ -563,21 +563,21 @@ follows (see also~\xref{fig:concepts.methods.stdmeth}). 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. @@ -598,7 +598,7 @@ follows (see also~\xref{fig:concepts.methods.stdmeth}). 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'.) @@ -609,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, @@ -619,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 @@ -639,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. @@ -960,12 +960,12 @@ 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