X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/54cf3a30e8463656e31629b50c655dad18ae5f9b..5cf27cf1ad4bd072c995c4fd8f353a6351c94e1f:/doc/concepts.tex

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 73ce9ed..6b21109 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -63,22 +63,33 @@ having to implement additional syntax.
 For the most part, Sod takes a fairly traditional view of what it means to be
 an object system.
 
-An \emph{object} maintains \emph{state} and exhibits \emph{behaviour}.  An
-object's state is maintained in named \emph{slots}, each of which can store a
-C value of an appropriate (scalar or aggregate) type.  An object's behaviour
-is stimulated by sending it \emph{messages}.  A message has a name, and may
-carry a number of arguments, which are C values; sending a message may result
-in the state of receiving object (or other objects) being changed, and a C
-value being returned to the sender.
-
-Every object is a (direct) instance of some \emph{class}.  The class
-determines which slots its instances have, which messages its instances can
-be sent, and which methods are invoked when those messages are received.  The
-Sod translator's main job is to read class definitions and convert them into
-appropriate C declarations, tables, and functions.  An object cannot
+An \emph{object} maintains \emph{state} and exhibits \emph{behaviour}.
+(Here, we're using the term `object' in the usual sense of `object-oriented
+programming', rather than that of the ISO~C standard.  Once we have defined
+an `instance' below, we shall generally prefer that term, so as to prevent
+further confusion between these two uses of the word.)
+
+An object's state is maintained in named \emph{slots}, each of which can
+store a C value of an appropriate (scalar or aggregate) type.  An object's
+behaviour is stimulated by sending it \emph{messages}.  A message has a name,
+and may carry a number of arguments, which are C values; sending a message
+may result in the state of receiving object (or other objects) being changed,
+and a C value being returned to the sender.
+
+Every object is a \emph{direct instance} of exactly one \emph{class}.  The
+class determines which slots its instances have, which messages its instances
+can be sent, and which methods are invoked when those messages are received.
+The Sod translator's main job is to read class definitions and convert them
+into appropriate C declarations, tables, and functions.  An object cannot
 (usually) change its direct class, and the direct class of an object is not
 affected by, for example, the static type of a pointer to it.
 
+If an object~$x$ is a direct instance of some class~$C$, then we say that $C$
+is \emph{the class of}~$x$.  Note that the class of an object is a property
+of the object's value at runtime, and not of C's compile-time type system.
+We shall be careful in distinguishing C's compile-time notion of \emph{type}
+from Sod's run-time notion of \emph{class}.
+
 
 \subsection{Superclasses and inheritance}
 \label{sec:concepts.classes.inherit}
@@ -120,7 +131,7 @@ class then the only superclass of $C$ is $C$ itself, and $C$ has no proper
 superclasses.
 
 If an object is a direct instance of class~$C$ then the object is also an
-(indirect) instance of every superclass of $C$.
+(indirect) \emph{instance} of every superclass of $C$.
 
 If $C$ has a proper superclass $B$, then $B$ must not have $C$ as a direct
 superclass.  In different terms, if we construct a directed graph, whose
@@ -276,6 +287,7 @@ class in a chain is called the \emph{chain head}; the most specific class is
 the \emph{chain tail}.  Chains are often named after their chain head
 classes.
 
+
 \subsection{Names}
 \label{sec:concepts.classes.names}
 
@@ -333,6 +345,9 @@ details.
 
 \subsection{C language integration} \label{sec:concepts.classes.c}
 
+It is very important to distinguish compile-time C \emph{types} from Sod's
+run-time \emph{classes}: see \xref{sec:concepts.classes}.
+
 For each class~$C$, the Sod translator defines a C type, the \emph{class
 type}, with the same name.  This is the usual type used when considering an
 object as an instance of class~$C$.  No entire object will normally have a
@@ -342,6 +357,10 @@ class type,\footnote{%
   chains.  See \xref{sec:structures.layout} for the full details.} %
 so access to instances is almost always via pointers.
 
+Usually, a value of type pointer-to-class-type of class~$C$ will point into
+an instance of class $C$.  However, clever (or foolish) use of pointer
+conversions can invalidate this relationship.
+
 \subsubsection{Access to slots}
 The class type for a class~$C$ is actually a structure.  It contains one
 member for each class in $C$'s superclass chain, named with that class's
@@ -349,8 +368,14 @@ nickname.  Each of these members is also a structure, containing the
 corresponding class's slots, one member per slot.  There's nothing special
 about these slot members: C code can access them in the usual way.
 
-For example, if @|MyClass| has the nickname @|mine|, and defines a slot @|x|
-of type @|int|, then the simple function
+For example, given the definition
+\begin{prog}
+  [nick = mine]                                                 \\
+  class MyClass: SodObject \{                                   \\ \ind
+    int x;                                                    \-\\
+  \}
+\end{prog}
+the simple function
 \begin{prog}
   int get_x(MyClass *m) \{ return (m@->mine.x); \}
 \end{prog}
@@ -363,6 +388,11 @@ 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:concepts.compatibility} for more details.)
 
+Slots defined by $C$'s link superclass, or any other superclass in the same
+chain, can be accessed in the same way.  Slots defined by other superclasses
+can't be accessed directly: the instance pointer must be \emph{converted} to
+point to a different chain.  See the subsection `Conversions' below.
+
 
 \subsubsection{Sending messages}
 Sod defines a macro for each message.  If a class $C$ defines a message $m$,
@@ -504,6 +534,13 @@ Keyword arguments can be provided in three ways.
   call, which is useful when writing wrapper functions.
 \end{enumerate}
 
+Perhaps surprisingly, keyword arguments have a relatively small performance
+impact.  On the author's aging laptop, a call to a simple function, passing
+two out of three keyword arguments, takes about 30 cycles longer than calling
+a standard function which just takes integer arguments.  On the other hand,
+quite a lot of code is involved in decoding keyword arguments, so code size
+will naturally suffer.
+
 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 rôle in
@@ -812,8 +849,6 @@ in \xref{sec:fixme.custom-aggregating-method-combination}.
 
 \subsection{Method entries} \label{sec:concepts.methods.entry}
 
-Each instance is associated with its direct class \fixme{direct instances}
-
 The effective methods for each class are determined at translation time, by
 the Sod translator.  For each effective method, one or more \emph{method
 entry functions} are constructed.  A method entry function has three
@@ -852,11 +887,10 @@ While method combinations may set their own rules, usually keyword methods
 can only be defined on keyword messages, and all methods defined on a keyword
 message must be keyword methods.  The direct methods defined on a keyword
 message may differ in the keywords they accept, both from each other, and
-from the message.  If two superclasses of some common class both define
-keyword methods on the same message, and the methods both accept a keyword
-argument with the same name, then these two keyword arguments must also have
-the same type.  Different applicable methods may declare keyword arguments
-with the same name but different defaults; see below.
+from the message.  If two applicable methods on the same message both accept
+a keyword argument with the same name, then these two keyword arguments must
+also have the same type.  Different applicable methods may declare keyword
+arguments with the same name but different defaults; see below.
 
 The keyword arguments acceptable in a message sent to an object are the
 keywords listed in the message definition, together with all of the keywords