From f4e44f7fecfaf1ee150d77e3e6ce115920277bbd Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 27 Jul 2019 14:41:14 +0100
Subject: [PATCH] doc/concepts.tex: Rearrange message-sending documentation.

Replace `Vtables' stub under `C language integration' with `Sending
messages', and write some stuff.  Rename `Sending messages in C' under
`Messages and methods' to `Method entries'.
---
 doc/concepts.tex | 45 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 5cb57bc..394913c 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -274,7 +274,48 @@ the private structure can grow more members as needed.  See
 \xref{sec:concepts.compatibility} for more details.)
 
 
-\subsubsection{Vtables}
+\subsubsection{Sending messages}
+Sod defines a macro for each message.  If a class $C$ defines a message $m$,
+then the macro is called @|$C$_$m$|.  The macro takes a pointer to the
+receiving object as its first argument, followed by the message arguments, if
+any, and returns the value returned by the object's effective method for the
+message (if any).  If you have a pointer to an instance of any of $C$'s
+subclasses, then you can send it the message; it doesn't matter whether the
+subclass is on the same chain.  Note that the receiver argument is evaluated
+twice, so it's not safe to write a receiver expression which has
+side-effects.
+
+For example, suppose we defined
+\begin{prog}
+  [nick = soupy]                                                \\
+  class Super: SodObject \{                                     \\ \ind
+    void msg(const char *m);                                  \-\\
+  \}                                                            \\+
+  class Sub: Super \{                                           \\ \ind
+    void soupy.msg(const char *m)
+      \{ printf("sub sent `\%s'@\\n", m); \}                  \-\\
+  \}
+\end{prog}
+then we can send the message like this:
+\begin{prog}
+  Sub *sub = /* \dots\ */;                                      \\
+  Super_msg(sub, "hello");
+\end{prog}
+
+What happens under the covers is as follows.  The structure pointed to by the
+instance pointer has a member named @|_vt|, which points to a structure
+called a `virtual table', or \emph{vtable}, which contains various pieces of
+information about the object's direct class and layout, and holds pointers to
+method entries for the messages which the object can receive.  The
+message-sending macro in the example above expands to something similar to
+\begin{prog}
+  sub@->_vt.sub.msg(sub, "Hello");
+\end{prog}
+
+The vtable contains other useful information, such as a pointer to the
+instance's direct class's \emph{class object} (described below).  The full
+details of the contents and layout of vtables are given in
+\xref{sec:structures.layout.vtable}.
 
 
 \subsubsection{Class objects}
@@ -679,7 +720,7 @@ There is also a @|custom| aggregating method combination, which is described
 in \xref{sec:fixme.custom-aggregating-method-combination}.
 
 
-\subsection{Sending messages in C} \label{sec:concepts.methods.c}
+\subsection{Method entries} \label{sec:concepts.methods.entry}
 
 Each instance is associated with its direct class \fixme{direct instances}
 
-- 
2.11.0