3 %%% Conceptual background
5 %%% (c) 2015 Straylight/Edgeware
8 %%%----- Licensing notice ---------------------------------------------------
10 %%% This file is part of the Sensible Object Design, an object system for C.
12 %%% SOD is free software; you can redistribute it and/or modify
13 %%% it under the terms of the GNU General Public License as published by
14 %%% the Free Software Foundation; either version 2 of the License, or
15 %%% (at your option) any later version.
17 %%% SOD is distributed in the hope that it will be useful,
18 %%% but WITHOUT ANY WARRANTY; without even the implied warranty of
19 %%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 %%% GNU General Public License for more details.
22 %%% You should have received a copy of the GNU General Public License
23 %%% along with SOD; if not, write to the Free Software Foundation,
24 %%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
26 \chapter{Concepts} \label{ch:concepts}
28 %%%--------------------------------------------------------------------------
29 \section{Modules} \label{sec:concepts.modules}
31 A \emph{module} is the top-level syntactic unit of input to the Sod
32 translator. As described above, given an input module, the translator
33 generates C source and header files.
35 A module can \emph{import} other modules. This makes the type names and
36 classes defined in those other modules available to class definitions in the
37 importing module. Sod's module system is intentionally very simple. There
38 are no private declarations or attempts to hide things.
40 As well as importing existing modules, a module can include a number of
41 different kinds of \emph{items}:
43 \item \emph{class definitions} describe new classes, possibly in terms of
45 \item \emph{type name declarations} introduce new type names to Sod's
47 This is unfortunately necessary because C syntax, upon which Sod's input
48 language is based for obvious reasons, needs to treat type names
49 differently from other kinds of identifiers.} %
51 \item \emph{code fragments} contain literal C code to be dropped into an
52 appropriate place in an output file.
54 Each kind of item, and, indeed, a module as a whole, can have a collection of
55 \emph{properties} associated with it. A property has a \emph{name} and a
56 \emph{value}. Properties are an open-ended way of attaching additional
57 information to module items, so extensions can make use of them without
58 having to implement additional syntax.
60 %%%--------------------------------------------------------------------------
61 \section{Classes, instances, and slots} \label{sec:concepts.classes}
63 For the most part, Sod takes a fairly traditional view of what it means to be
66 An \emph{object} maintains \emph{state} and exhibits \emph{behaviour}.
67 (Here, we're using the term `object' in the usual sense of `object-oriented
68 programming', rather than that of the ISO~C standard. Once we have defined
69 an `instance' below, we shall generally prefer that term, so as to prevent
70 further confusion between these two uses of the word.)
72 An object's state is maintained in named \emph{slots}, each of which can
73 store a C value of an appropriate (scalar or aggregate) type. An object's
74 behaviour is stimulated by sending it \emph{messages}. A message has a name,
75 and may carry a number of arguments, which are C values; sending a message
76 may result in the state of receiving object (or other objects) being changed,
77 and a C value being returned to the sender.
79 Every object is a \emph{direct instance} of exactly one \emph{class}. The
80 class determines which slots its instances have, which messages its instances
81 can be sent, and which methods are invoked when those messages are received.
82 The Sod translator's main job is to read class definitions and convert them
83 into appropriate C declarations, tables, and functions. An object cannot
84 (usually) change its direct class, and the direct class of an object is not
85 affected by, for example, the static type of a pointer to it.
87 If an object~$x$ is a direct instance of some class~$C$, then we say that $C$
88 is \emph{the class of}~$x$. Note that the class of an object is a property
89 of the object's value at runtime, and not of C's compile-time type system.
90 We shall be careful in distinguishing C's compile-time notion of \emph{type}
91 from Sod's run-time notion of \emph{class}.
94 \subsection{Superclasses and inheritance}
95 \label{sec:concepts.classes.inherit}
97 \subsubsection{Class relationships}
98 Each class has zero or more \emph{direct superclasses}.
100 A class with no direct superclasses is called a \emph{root class}. The Sod
101 runtime library includes a root class named @|SodObject|; making new root
102 classes is somewhat tricky, and won't be discussed further here.
104 Classes can have more than one direct superclass, i.e., Sod supports
105 \emph{multiple inheritance}. A Sod class definition for a class~$C$ lists
106 the direct superclasses of $C$ in a particular order. This order is called
107 the \emph{local precedence order} of $C$, and the list which consists of $C$
108 follows by $C$'s direct superclasses in local precedence order is called the
109 $C$'s \emph{local precedence list}.
111 The multiple inheritance in Sod works similarly to multiple inheritance in
112 Lisp-like languages, such as Common Lisp, EuLisp, Dylan, and Python, which is
113 very different from how multiple inheritance works in \Cplusplus.\footnote{%
114 The latter can be summarized as `badly'. By default in \Cplusplus, an
115 instance receives an additional copy of superclass's state for each path
116 through the class graph from the instance's direct class to that
117 superclass, though this behaviour can be overridden by declaring
118 superclasses to be @|virtual|. Also, \Cplusplus\ offers only trivial
119 method combination (\xref{sec:concepts.methods}), leaving programmers to
120 deal with delegation manually and (usually) statically.} %
122 If $C$ is a class, then the \emph{superclasses} of $C$ are
124 \item $C$ itself, and
125 \item the superclasses of each of $C$'s direct superclasses.
127 The \emph{proper superclasses} of a class $C$ are the superclasses of $C$
128 except for $C$ itself. If a class $B$ is a (direct, proper) superclass of
129 $C$, then $C$ is a \emph{(direct, proper) subclass} of $B$. If $C$ is a root
130 class then the only superclass of $C$ is $C$ itself, and $C$ has no proper
133 If an object is a direct instance of class~$C$ then the object is also an
134 (indirect) \emph{instance} of every superclass of $C$.
136 If $C$ has a proper superclass $B$, then $B$ must not have $C$ as a direct
137 superclass. In different terms, if we construct a directed graph, whose
138 nodes are classes, and draw an arc from each class to each of its direct
139 superclasses, then this graph must be acyclic. In yet other terms, the `is a
140 superclass of' relation is a partial order on classes.
142 \subsubsection{The class precedence list}
143 This partial order is not quite sufficient for our purposes. For each class
144 $C$, we shall need to extend it into a total order on $C$'s superclasses.
145 This calculation is called \emph{superclass linearization}, and the result is
146 a \emph{class precedence list}, which lists each of $C$'s superclasses
147 exactly once. If a superclass $B$ precedes (resp.\ follows) some other
148 superclass $A$ in $C$'s class precedence list, then we say that $B$ is a more
149 (resp.\ less) \emph{specific} superclass of $C$ than $A$ is.
151 The superclass linearization algorithm isn't fixed, and extensions to the
152 translator can introduce new linearizations for special effects, but the
153 following properties are expected to hold.
155 \item The first class in $C$'s class precedence list is $C$ itself; i.e.,
156 $C$ is always its own most specific superclass.
157 \item If $A$ and $B$ are both superclasses of $C$, and $A$ is a proper
158 superclass of $B$ then $A$ appears after $B$ in $C$'s class precedence
159 list, i.e., $B$ is a more specific superclass of $C$ than $A$ is.
161 The default linearization algorithm used in Sod is the \emph{C3} algorithm,
162 which has a number of good properties described in~\cite{Barrett:1996:MSL}.
165 \item A \emph{merge} of some number of input lists is a single list
166 containing each item that is in any of the input lists exactly once, and no
167 other items; if an item $x$ appears before an item $y$ in any input list,
168 then $x$ also appears before $y$ in the merge. If a collection of lists
169 have no merge then they are said to be \emph{inconsistent}.
170 \item The class precedence list of a class $C$ is a merge of the local
171 precedence list of $C$ together with the class precedence lists of each of
172 $C$'s direct superclasses.
173 \item If there are no such merges, then the definition of $C$ is invalid.
174 \item Suppose that there are multiple candidate merges. Consider the
175 earliest position in these candidate merges at which they disagree. The
176 \emph{candidate classes} at this position are the classes appearing at this
177 position in the candidate merges. Each candidate class must be a
178 superclass of distinct direct superclasses of $C$, since otherwise the
179 candidates would be ordered by their common subclass's class precedence
180 list. The class precedence list contains, at this position, that candidate
181 class whose subclass appears earliest in $C$'s local precedence order.
186 \begin{tikzpicture}[x=7.5mm, y=-14mm, baseline=(current bounding box.east)]
187 \node[lit] at ( 0, 0) (R) {SodObject};
188 \node[lit] at (-3, +1) (A) {A}; \draw[->] (A) -- (R);
189 \node[lit] at (-1, +1) (B) {B}; \draw[->] (B) -- (R);
190 \node[lit] at (+1, +1) (C) {C}; \draw[->] (C) -- (R);
191 \node[lit] at (+3, +1) (D) {D}; \draw[->] (D) -- (R);
192 \node[lit] at (-2, +2) (E) {E}; \draw[->] (E) -- (A);
193 \draw[->] (E) -- (B);
194 \node[lit] at (+2, +2) (F) {F}; \draw[->] (F) -- (A);
195 \draw[->] (F) -- (D);
196 \node[lit] at (-1, +3) (G) {G}; \draw[->] (G) -- (E);
197 \draw[->] (G) -- (C);
198 \node[lit] at (+1, +3) (H) {H}; \draw[->] (H) -- (F);
199 \node[lit] at ( 0, +4) (I) {I}; \draw[->] (I) -- (G);
200 \draw[->] (I) -- (H);
205 \begin{minipage}[c]{0.45\hsize}
207 class A: SodObject \{ \}\quad\=@/* @|A|, @|SodObject| */ \\
208 class B: SodObject \{ \}\>@/* @|B|, @|SodObject| */ \\
209 class C: SodObject \{ \}\>@/* @|B|, @|SodObject| */ \\
210 class D: SodObject \{ \}\>@/* @|B|, @|SodObject| */ \\+
211 class E: A, B \{ \}\quad\=@/* @|E|, @|A|, @|B|, \dots */ \\
212 class F: A, D \{ \}\>@/* @|F|, @|A|, @|D|, \dots */ \\+
213 class G: E, C \{ \}\>@/* @|G|, @|E|, @|A|,
214 @|B|, @|C|, \dots */ \\
215 class H: F \{ \}\>@/* @|H|, @|F|, @|A|, @|D|, \dots */ \\+
216 class I: G, H \{ \}\>@/* @|I|, @|G|, @|E|, @|H|, @|F|,
217 @|A|, @|B|, @|C|, @|D|, \dots */
221 \caption{An example class graph and class precedence lists}
222 \label{fig:concepts.classes.cpl-example}
226 Consider the class relationships shown in
227 \xref{fig:concepts.classes.cpl-example}.
231 \item @|SodObject| has no proper superclasses. Its class precedence list
232 is therefore simply $\langle @|SodObject| \rangle$.
234 \item In general, if $X$ is a direct subclass only of $Y$, and $Y$'s class
235 precedence list is $\langle Y, \ldots \rangle$, then $X$'s class
236 precedence list is $\langle X, Y, \ldots \rangle$. This explains $A$,
237 $B$, $C$, $D$, and $H$.
239 \item $E$'s list is found by merging its local precedence list $\langle E,
240 A, B \rangle$ with the class precedence lists of its direct superclasses,
241 which are $\langle A, @|SodObject| \rangle$ and $\langle B, @|SodObject|
242 \rangle$. Clearly, @|SodObject| must be last, and $E$'s local precedence
243 list orders the rest, giving $\langle E, A, B, @|SodObject|, \rangle$.
246 \item We determine $G$'s class precedence list by merging the three lists
247 $\langle G, E, C \rangle$, $\langle E, A, B, @|SodObject| \rangle$, and
248 $\langle C, @|SodObject| \rangle$. The class precedence list begins
249 $\langle G, E, \ldots \rangle$, but the individual lists don't order $A$
250 and $C$. Comparing these to $G$'s direct superclasses, we see that $A$
251 is a superclass of $E$, while $C$ is a superclass of -- indeed equal to
252 -- $C$; so $A$ must precede $C$, as must $B$, and the final list is
253 $\langle G, E, A, B, C, @|SodObject| \rangle$.
255 \item Finally, we determine $I$'s class precedence list by merging $\langle
256 I, G, H \rangle$, $\langle G, E, A, B, C, @|SodObject| \rangle$, and
257 $\langle H, F, A, D, @|SodObject| \rangle$. The list begins $\langle I,
258 G, \ldots \rangle$, and then we must break a tie between $E$ and $H$; but
259 $E$ is a superclass of $G$, so $E$ wins. Next, $H$ and $F$ must precede
260 $A$, since these are ordered by $H$'s class precedence list. Then $B$
261 and $C$ precede $D$, since the former are superclasses of $G$, and the
262 final list is $\langle I, G, E, H, F, A, B, C, D, @|SodObject| \rangle$.
266 (This example combines elements from \cite{Barrett:1996:MSL} and
267 \cite{Ducournau:1994:PMM}.)
270 \subsubsection{Class links and chains}
271 The definition for a class $C$ may distinguish one of its proper superclasses
272 as being the \emph{link superclass} for class $C$. Not every class need have
273 a link superclass, and the link superclass of a class $C$, if it exists, need
274 not be a direct superclass of $C$.
276 Superclass links must obey the following rule: if $C$ is a class, then there
277 must be no three distinct superclasses $X$, $Y$ and~$Z$ of $C$ such that $Z$
278 is the link superclass of both $X$ and $Y$. As a consequence of this rule,
279 the superclasses of $C$ can be partitioned into linear \emph{chains}, such
280 that superclasses $A$ and $B$ are in the same chain if and only if one can
281 trace a path from $A$ to $B$ by following superclass links, or \emph{vice
284 Since a class links only to one of its proper superclasses, the classes in a
285 chain are naturally ordered from most- to least-specific. The least specific
286 class in a chain is called the \emph{chain head}; the most specific class is
287 the \emph{chain tail}. Chains are often named after their chain head
292 \label{sec:concepts.classes.names}
294 Classes have a number of other attributes:
296 \item A \emph{name}, which is a C identifier. Class names must be globally
297 unique. The class name is used in the names of a number of associated
298 definitions, to be described later.
299 \item A \emph{nickname}, which is also a C identifier. Unlike names,
300 nicknames are not required to be globally unique. If $C$ is any class,
301 then all the superclasses of $C$ must have distinct nicknames.
305 \subsection{Slots} \label{sec:concepts.classes.slots}
307 Each class defines a number of \emph{slots}. Much like a structure member, a
308 slot has a \emph{name}, which is a C identifier, and a \emph{type}. Unlike
309 many other object systems, different superclasses of a class $C$ can define
310 slots with the same name without ambiguity, since slot references are always
311 qualified by the defining class's nickname.
313 \subsubsection{Slot initializers}
314 As well as defining slot names and types, a class can also associate an
315 \emph{initial value} with each slot defined by itself or one of its
316 subclasses. A class $C$ provides an \emph{initialization message} (see
317 \xref{sec:concepts.lifecycle.birth}, and \xref{sec:structures.root.sodclass})
318 whose methods set the slots of a \emph{direct} instance of the class to the
319 correct initial values. If several of $C$'s superclasses define initializers
320 for the same slot then the initializer from the most specific such class is
321 used. If none of $C$'s superclasses define an initializer for some slot then
322 that slot will be left uninitialized.
324 The initializer for a slot with scalar type may be any C expression. The
325 initializer for a slot with aggregate type must contain only constant
326 expressions if the generated code is expected to be processed by a
327 implementation of C89. Initializers will be evaluated once each time an
328 instance is initialized.
330 Slots are initialized in reverse-precedence order of their defining classes;
331 i.e., slots defined by a less specific superclass are initialized earlier
332 than slots defined by a more specific superclass. Slots defined by the same
333 class are initialized in the order in which they appear in the class
336 The initializer for a slot may refer to other slots in the same object, via
337 the @|me| pointer: in an initializer for a slot defined by a class $C$, @|me|
338 has type `pointer to $C$'. (Note that the type of @|me| depends only on the
339 class which defined the slot, not the class which defined the initializer.)
341 A class can also define \emph{class slot initializers}, which provide values
342 for a slot defined by its metaclass; see \xref{sec:concepts.metaclasses} for
346 \subsection{C language integration} \label{sec:concepts.classes.c}
348 For each class~$C$, the Sod translator defines a C type, the \emph{class
349 type}, with the same name. This is the usual type used when considering an
350 object as an instance of class~$C$. No entire object will normally have a
351 class type,\footnote{%
352 In general, a class type only captures the structure of one of the
353 superclass chains of an instance. A full instance layout contains multiple
354 chains. See \xref{sec:structures.layout} for the full details.} %
355 so access to instances is almost always via pointers.
357 \subsubsection{Access to slots}
358 The class type for a class~$C$ is actually a structure. It contains one
359 member for each class in $C$'s superclass chain, named with that class's
360 nickname. Each of these members is also a structure, containing the
361 corresponding class's slots, one member per slot. There's nothing special
362 about these slot members: C code can access them in the usual way.
364 For example, given the definition
367 class MyClass: SodObject \{ \\ \ind
373 int get_x(MyClass *m) \{ return (m@->mine.x); \}
375 will extract the value of @|x| from an instance of @|MyClass|.
377 All of this means that there's no such thing as `private' or `protected'
378 slots. If you want to hide implementation details, the best approach is to
379 stash them in a dynamically allocated private structure, and leave a pointer
380 to it in a slot. (This will also help preserve binary compatibility, because
381 the private structure can grow more members as needed. See
382 \xref{sec:concepts.compatibility} for more details.)
384 Slots defined by $C$'s link superclass, or any other superclass in the same
385 chain, can be accessed in the same way. Slots defined by other superclasses
386 can't be accessed directly: the instance pointer must be \emph{converted} to
387 point to a different chain. See the subsection `Conversions' below.
390 \subsubsection{Sending messages}
391 Sod defines a macro for each message. If a class $C$ defines a message $m$,
392 then the macro is called @|$C$_$m$|. The macro takes a pointer to the
393 receiving object as its first argument, followed by the message arguments, if
394 any, and returns the value returned by the object's effective method for the
395 message (if any). If you have a pointer to an instance of any of $C$'s
396 subclasses, then you can send it the message; it doesn't matter whether the
397 subclass is on the same chain. Note that the receiver argument is evaluated
398 twice, so it's not safe to write a receiver expression which has
401 For example, suppose we defined
404 class Super: SodObject \{ \\ \ind
405 void msg(const char *m); \-\\
407 class Sub: Super \{ \\ \ind
408 void soupy.msg(const char *m)
409 \{ printf("sub sent `\%s'@\\n", m); \} \-\\
412 then we can send the message like this:
414 Sub *sub = /* \dots\ */; \\
415 Super_msg(sub, "hello");
418 What happens under the covers is as follows. The structure pointed to by the
419 instance pointer has a member named @|_vt|, which points to a structure
420 called a `virtual table', or \emph{vtable}, which contains various pieces of
421 information about the object's direct class and layout, and holds pointers to
422 method entries for the messages which the object can receive. The
423 message-sending macro in the example above expands to something similar to
425 sub@->_vt.sub.msg(sub, "Hello");
428 The vtable contains other useful information, such as a pointer to the
429 instance's direct class's \emph{class object} (described below). The full
430 details of the contents and layout of vtables are given in
431 \xref{sec:structures.layout.vtable}.
434 \subsubsection{Class objects}
435 In Sod's object system, classes are objects too. Therefore classes are
436 themselves instances; the class of a class is called a \emph{metaclass}. The
437 consequences of this are explored in \xref{sec:concepts.metaclasses}. The
438 \emph{class object} has the same name as the class, suffixed with
439 `@|__class|'\footnote{%
440 This is not quite true. @|$C$__class| is actually a macro. See
441 \xref{sec:structures.layout.additional} for the gory details.} %
442 and its type is usually @|SodClass|; @|SodClass|'s nickname is @|cls|.
444 A class object's slots contain or point to useful information, tables and
445 functions for working with that class's instances. (The @|SodClass| class
446 doesn't define any messages, so it doesn't have any methods other than for
447 the @|SodObject| lifecycle messages @|init| and @|teardown|; see
448 \xref{sec:concepts.lifecycle}. In Sod, a class slot containing a function
449 pointer is not at all the same thing as a method.)
451 \subsubsection{Conversions}
452 Suppose one has a value of type pointer-to-class-type for some class~$C$, and
453 wants to convert it to a pointer-to-class-type for some other class~$B$.
454 There are three main cases to distinguish.
456 \item If $B$ is a superclass of~$C$, in the same chain, then the conversion
457 is an \emph{in-chain upcast}. The conversion can be performed using the
458 appropriate generated upcast macro (see below), or by simply casting the
459 pointer, using C's usual cast operator (or the \Cplusplus\ @|static_cast<>|
461 \item If $B$ is a superclass of~$C$, in a different chain, then the
462 conversion is a \emph{cross-chain upcast}. The conversion is more than a
463 simple type change: the pointer value must be adjusted. If the direct
464 class of the instance in question is not known, the conversion will require
465 a lookup at runtime to find the appropriate offset by which to adjust the
466 pointer. The conversion can be performed using the appropriate generated
467 upcast macro (see below); the general case is handled by the macro
468 \descref{SOD_XCHAIN}{mac}.
469 \item If $B$ is a subclass of~$C$ then the conversion is a \emph{downcast};
470 otherwise the conversion is a~\emph{cross-cast}. In either case, the
471 conversion can fail: the object in question might not be an instance of~$B$
472 after all. The macro \descref{SOD_CONVERT}{mac} and the function
473 \descref{sod_convert}{fun} perform general conversions. They return a null
474 pointer if the conversion fails. (These are therefore your analogue to the
475 \Cplusplus\ @|dynamic_cast<>| operator.)
477 The Sod translator generates macros for performing both in-chain and
478 cross-chain upcasts. For each class~$C$, and each proper superclass~$B$
479 of~$C$, a macro is defined: given an argument of type pointer to class type
480 of~$C$, it returns a pointer to the same instance, only with type pointer to
481 class type of~$B$, adjusted as necessary in the case of a cross-chain
482 conversion. The macro is named by concatenating
484 \item the name of class~$C$, in upper case,
485 \item the characters `@|__CONV_|', and
486 \item the nickname of class~$B$, in upper case;
488 e.g., if $C$ is named @|MyClass|, and $B$'s name is @|SuperClass| with
489 nickname @|super|, then the macro @|MYCLASS__CONV_SUPER| converts a
490 @|MyClass~*| to a @|SuperClass~*|. See
491 \xref{sec:structures.layout.additional} for the formal description.
493 %%%--------------------------------------------------------------------------
494 \section{Keyword arguments} \label{sec:concepts.keywords}
496 In standard C, the actual arguments provided to a function are matched up
497 with the formal arguments given in the function definition according to their
498 ordering in a list. Unless the (rather cumbersome) machinery for dealing
499 with variable-length argument tails (@|<stdarg.h>|) is used, exactly the
500 correct number of arguments must be supplied, and in the correct order.
502 A \emph{keyword argument} is matched by its distinctive \emph{name}, rather
503 than by its position in a list. Keyword arguments may be \emph{omitted},
504 causing some default behaviour by the function. A function can detect
505 whether a particular keyword argument was supplied: so the default behaviour
506 need not be the same as that caused by any specific value of the argument.
508 Keyword arguments can be provided in three ways.
510 \item Directly, as a variable-length argument tail, consisting (for the most
511 part) of alternating keyword names, as pointers to null-terminated strings,
512 and argument values, and terminated by a null pointer. This is somewhat
513 error-prone, and the support library defines some macros which help ensure
514 that keyword argument lists are well formed.
515 \item Indirectly, through a @|va_list| object capturing a variable-length
516 argument tail passed to some other function. Such indirect argument tails
517 have the same structure as the direct argument tails described above.
518 Because @|va_list| objects are hard to copy, the keyword-argument support
519 library consistently passes @|va_list| objects \emph{by reference}
520 throughout its programming interface.
521 \item Indirectly, through a vector of @|struct kwval| objects, each of which
522 contains a keyword name, as a pointer to a null-terminated string, and the
523 \emph{address} of a corresponding argument value. (This indirection is
524 necessary so that the items in the vector can be of uniform size.)
525 Argument vectors are rather inconvenient to use, but are the only practical
526 way in which a caller can decide at runtime which arguments to include in a
527 call, which is useful when writing wrapper functions.
530 Keyword arguments are provided as a general feature for C functions.
531 However, Sod has special support for messages which accept keyword arguments
532 (\xref{sec:concepts.methods.keywords}); and they play an essential rôle in
533 the instance construction protocol (\xref{sec:concepts.lifecycle.birth}).
535 %%%--------------------------------------------------------------------------
536 \section{Messages and methods} \label{sec:concepts.methods}
538 Objects can be sent \emph{messages}. A message has a \emph{name}, and
539 carries a number of \emph{arguments}. When an object is sent a message, a
540 function, determined by the receiving object's class, is invoked, passing it
541 the receiver and the message arguments. This function is called the
542 class's \emph{effective method} for the message. The effective method can do
543 anything a C function can do, including reading or updating program state or
544 object slots, sending more messages, calling other functions, issuing system
545 calls, or performing I/O; if it finishes, it may return a value, which is
546 returned in turn to the message sender.
548 The set of messages an object can receive, characterized by their names,
549 argument types, and return type, is determined by the object's class. Each
550 class can define new messages, which can be received by any instance of that
551 class. The messages defined by a single class must have distinct names:
552 there is no `function overloading'. As with slots
553 (\xref{sec:concepts.classes.slots}), messages defined by distinct classes are
554 always distinct, even if they have the same names: references to messages are
555 always qualified by the defining class's name or nickname.
557 Messages may take any number of arguments, of any non-array value type.
558 Since message sends are effectively function calls, arguments of array type
559 are implicitly converted to values of the corresponding pointer type. While
560 message definitions may ascribe an array type to an argument, the formal
561 argument will have pointer type, as is usual for C functions. A message may
562 accept a variable-length argument suffix, denoted @|\dots|.
564 A class definition may include \emph{direct methods} for messages defined by
565 it or any of its superclasses.
567 Like messages, direct methods define argument lists and return types, but
568 they may also have a \emph{body}, and a \emph{rôle}.
570 A direct method need not have the same argument list or return type as its
571 message. The acceptable argument lists and return types for a method depend
572 on the message, in particular its method combination
573 (\xref{sec:concepts.methods.combination}), and the method's rôle.
575 A direct method body is a block of C code, and the Sod translator usually
576 defines, for each direct method, a function with external linkage, whose body
577 contains a copy of the direct method body. Within the body of a direct
578 method defined for a class $C$, the variable @|me|, of type pointer to class
579 type of $C$, refers to the receiving object.
582 \subsection{Effective methods and method combinations}
583 \label{sec:concepts.methods.combination}
585 For each message a direct instance of a class might receive, there is a set
586 of \emph{applicable methods}, which are exactly the direct methods defined on
587 the object's class and its superclasses. These direct methods are combined
588 together to form the \emph{effective method} for that particular class and
589 message. Direct methods can be combined into an effective method in
590 different ways, according to the \emph{method combination} specified by the
591 message. The method combination determines which direct method rôles are
592 acceptable, and, for each rôle, the appropriate argument lists and return
595 One direct method, $M$, is said to be more (resp.\ less) \emph{specific} than
596 another, $N$, with respect to a receiving class~$C$, if the class defining
597 $M$ is a more (resp.\ less) specific superclass of~$C$ than the class
600 \subsubsection{The standard method combination}
601 The default method combination is called the \emph{standard method
602 combination}; other method combinations are useful occasionally for special
603 effects. The standard method combination accepts four direct method rôles,
604 called `primary' (the default), @|before|, @|after|, and @|around|.
606 All direct methods subject to the standard method combination must have
607 argument lists which \emph{match} the message's argument list:
609 \item the method's arguments must have the same types as the message, though
610 the arguments may have different names; and
611 \item if the message accepts a variable-length argument suffix then the
612 direct method must instead have a final argument of type @|va_list|.
614 Primary and @|around| methods must have the same return type as the message;
615 @|before| and @|after| methods must return @|void| regardless of the
616 message's return type.
618 If there are no applicable primary methods then no effective method is
619 constructed: the vtables contain null pointers in place of pointers to method
623 \hbox to\hsize{\hss\hbox{\begin{tikzpicture}
624 [order/.append style={color=green!70!black},
625 code/.append style={font=\sffamily},
626 action/.append style={font=\itshape},
627 method/.append style={rectangle, draw=black, thin, fill=blue!30,
628 text height=\ht\strutbox, text depth=\dp\strutbox,
631 \def\delgstack#1#2#3{
632 \node (#10) [method, #2] {#3};
633 \node (#11) [method, above=6mm of #10] {#3};
634 \draw [->] ($(#10.north)!.5!(#10.north west) + (0mm, 1mm)$) --
636 node [code, left=4pt, midway] {next_method};
637 \draw [<-] ($(#10.north)!.5!(#10.north east) + (0mm, 1mm)$) --
639 node [action, right=4pt, midway] {return};
640 \draw [->] ($(#11.north)!.5!(#11.north west) + (0mm, 1mm)$) --
642 node [code, left=4pt, midway] {next_method}
643 node (ld) [above] {$\smash\vdots\mathstrut$};
644 \draw [<-] ($(#11.north)!.5!(#11.north east) + (0mm, 1mm)$) --
646 node [action, right=4pt, midway] {return}
647 node (rd) [above] {$\smash\vdots\mathstrut$};
648 \draw [->] ($(ld.north) + (0mm, 1mm)$) -- ++(0mm, 4mm)
649 node [code, left=4pt, midway] {next_method};
650 \draw [<-] ($(rd.north) + (0mm, 1mm)$) -- ++(0mm, 4mm)
651 node [action, right=4pt, midway] {return};
652 \node (p) at ($(ld.north)!.5!(rd.north)$) {};
653 \node (#1n) [method, above=5mm of p] {#3};
654 \draw [->, order] ($(#10.south east) + (4mm, 1mm)$) --
655 ($(#1n.north east) + (4mm, -1mm)$)
656 node [midway, right, align=left]
657 {Most to \\ least \\ specific};}
659 \delgstack{a}{}{@|around| method}
660 \draw [<-] ($(a0.south)!.5!(a0.south west) - (0mm, 1mm)$) --
662 \draw [->] ($(a0.south)!.5!(a0.south east) - (0mm, 1mm)$) --
664 node [action, right=4pt, midway] {return};
666 \draw [->] ($(an.north)!.6!(an.north west) + (0mm, 1mm)$) --
668 node [code, midway, left=3mm] {next_method}
669 node (b0) [method, above left = 1mm + 4mm and -6mm - 4mm] {};
670 \node (b1) [method] at ($(b0) - (2mm, 2mm)$) {};
671 \node (bn) [method] at ($(b1) - (2mm, 2mm)$) {@|before| method};
672 \draw [->, order] ($(bn.west) - (6mm, 0mm)$) -- ++(12mm, 12mm)
673 node [midway, above left, align=center] {Most to \\ least \\ specific};
674 \draw [->] ($(b0.north east) + (-10mm, 1mm)$) -- ++(8mm, 8mm)
677 \delgstack{m}{above right=1mm and 0mm of an.west |- p}{Primary method}
678 \draw [->] ($(mn.north)!.5!(mn.north west) + (0mm, 1mm)$) -- ++(0mm, 4mm)
679 node [code, left=4pt, midway] {next_method}
680 node [above right = 0mm and -8mm]
681 {$\vcenter{\hbox{\Huge\textcolor{red}{!}}}
682 \vcenter{\hbox{\begin{tabular}[c]{l}
683 \textsf{next_method} \\
687 \draw [->, color=blue, dotted]
688 ($(m0.south)!.2!(m0.south east) - (0mm, 1mm)$) --
689 ($(an.north)!.2!(an.north east) + (0mm, 1mm)$)
690 node [midway, sloped, below] {Return value};
692 \draw [<-] ($(an.north)!.6!(an.north east) + (0mm, 1mm)$) --
694 node [action, midway, right=3mm] {return}
695 node (f0) [method, above right = 1mm and -6mm] {};
696 \node (f1) [method] at ($(f0) + (-2mm, 2mm)$) {};
697 \node (fn) [method] at ($(f1) + (-2mm, 2mm)$) {@|after| method};
698 \draw [<-, order] ($(f0.east) + (6mm, 0mm)$) -- ++(-12mm, 12mm)
699 node [midway, above right, align=center]
700 {Least to \\ most \\ specific};
701 \draw [<-] ($(fn.north west) + (6mm, 1mm)$) -- ++(-8mm, 8mm);
703 \end{tikzpicture}}\hss}
705 \caption{The standard method combination}
706 \label{fig:concepts.methods.stdmeth}
709 The effective method for a message with standard method combination works as
710 follows (see also~\xref{fig:concepts.methods.stdmeth}).
713 \item If any applicable methods have the @|around| rôle, then the most
714 specific such method, with respect to the class of the receiving object, is
717 Within the body of an @|around| method, the variable @|next_method| is
718 defined, having pointer-to-function type. The method may call this
719 function, as described below, any number of times.
721 If there any remaining @|around| methods, then @|next_method| invokes the
722 next most specific such method, returning whichever value that method
723 returns; otherwise the behaviour of @|next_method| is to invoke the
724 @|before| methods (if any), followed by the most specific primary method,
725 followed by the @|after| methods (if any), and to return whichever value
726 was returned by the most specific primary method, as described in the
727 following items. That is, the behaviour of the least specific @|around|
728 method's @|next_method| function is exactly the behaviour that the
729 effective method would have if there were no @|around| methods. Note that
730 if the least-specific @|around| method calls its @|next_method| more than
731 once then the whole sequence of @|before|, primary, and @|after| methods
732 occurs multiple times.
734 The value returned by the most specific @|around| method is the value
735 returned by the effective method.
737 \item If any applicable methods have the @|before| rôle, then they are all
738 invoked, starting with the most specific.
740 \item The most specific applicable primary method is invoked.
742 Within the body of a primary method, the variable @|next_method| is
743 defined, having pointer-to-function type. If there are no remaining less
744 specific primary methods, then @|next_method| is a null pointer.
745 Otherwise, the method may call the @|next_method| function any number of
748 The behaviour of the @|next_method| function, if it is not null, is to
749 invoke the next most specific applicable primary method, and to return
750 whichever value that method returns.
752 If there are no applicable @|around| methods, then the value returned by
753 the most specific primary method is the value returned by the effective
754 method; otherwise the value returned by the most specific primary method is
755 returned to the least specific @|around| method, which called it via its
756 own @|next_method| function.
758 \item If any applicable methods have the @|after| rôle, then they are all
759 invoked, starting with the \emph{least} specific. (Hence, the most
760 specific @|after| method is invoked with the most `afterness'.)
764 A typical use for @|around| methods is to allow a base class to set up the
765 dynamic environment appropriately for the primary methods of its subclasses,
766 e.g., by claiming a lock, and releasing it afterwards.
768 The @|next_method| function provided to methods with the primary and
769 @|around| rôles accepts the same arguments, and returns the same type, as the
770 message, except that one or two additional arguments are inserted at the
771 front of the argument list. The first additional argument is always the
772 receiving object, @|me|. If the message accepts a variable argument suffix,
773 then the second addition argument is a @|va_list|; otherwise there is no
774 second additional argument; otherwise, In the former case, a variable
775 @|sod__master_ap| of type @|va_list| is defined, containing a separate copy
776 of the argument pointer (so the method body can process the variable argument
777 suffix itself, and still pass a fresh copy on to the next method).
779 A method with the primary or @|around| rôle may use the convenience macro
780 @|CALL_NEXT_METHOD|, which takes no arguments itself, and simply calls
781 @|next_method| with appropriate arguments: the receiver @|me| pointer, the
782 argument pointer @|sod__master_ap| (if applicable), and the method's
783 arguments. If the method body has overwritten its formal arguments, then
784 @|CALL_NEXT_METHOD| will pass along the updated values, rather than the
787 A primary or @|around| method which invokes its @|next_method| function is
788 said to \emph{extend} the message behaviour; a method which does not invoke
789 its @|next_method| is said to \emph{override} the behaviour. Note that a
790 method may make a decision to override or extend at runtime.
792 \subsubsection{Aggregating method combinations}
793 A number of other method combinations are provided. They are called
794 `aggregating' method combinations because, instead of invoking just the most
795 specific primary method, as the standard method combination does, they invoke
796 the applicable primary methods in turn and aggregate the return values from
799 The aggregating method combinations accept the same four rôles as the
800 standard method combination, and @|around|, @|before|, and @|after| methods
801 work in the same way.
803 The aggregating method combinations provided are as follows.
804 \begin{description} \let\makelabel\code
805 \item[progn] The message must return @|void|. The applicable primary methods
806 are simply invoked in turn, most specific first.
807 \item[sum] The message must return a numeric type.\footnote{%
808 The Sod translator does not check this, since it doesn't have enough
809 insight into @|typedef| names.} %
810 The applicable primary methods are invoked in turn, and their return values
811 added up. The final result is the sum of the individual values.
812 \item[product] The message must return a numeric type. The applicable
813 primary methods are invoked in turn, and their return values multiplied
814 together. The final result is the product of the individual values.
815 \item[min] The message must return a scalar type. The applicable primary
816 methods are invoked in turn. The final result is the smallest of the
818 \item[max] The message must return a scalar type. The applicable primary
819 methods are invoked in turn. The final result is the largest of the
821 \item[and] The message must return a scalar type. The applicable primary
822 methods are invoked in turn. If any method returns zero then the final
823 result is zero and no further methods are invoked. If all of the
824 applicable primary methods return nonzero, then the final result is the
825 result of the last primary method.
826 \item[or] The message must return a scalar type. The applicable primary
827 methods are invoked in turn. If any method returns nonzero then the final
828 result is that nonzero value and no further methods are invoked. If all of
829 the applicable primary methods return zero, then the final result is zero.
832 There is also a @|custom| aggregating method combination, which is described
833 in \xref{sec:fixme.custom-aggregating-method-combination}.
836 \subsection{Method entries} \label{sec:concepts.methods.entry}
838 The effective methods for each class are determined at translation time, by
839 the Sod translator. For each effective method, one or more \emph{method
840 entry functions} are constructed. A method entry function has three
843 \item It converts the receiver pointer to the correct type. Method entry
844 functions can perform these conversions extremely efficiently: there are
845 separate method entries for each chain of each class which can receive a
846 message, so method entry functions are in the privileged situation of
847 knowing the \emph{exact} class of the receiving object.
848 \item If the message accepts a variable-length argument tail, then two method
849 entry functions are created for each chain of each class: one receives a
850 variable-length argument tail, as intended, and captures it in a @|va_list|
851 object; the other accepts an argument of type @|va_list| in place of the
852 variable-length tail and arranges for it to be passed along to the direct
854 \item It invokes the effective method with the appropriate arguments. There
855 might or might not be an actual function corresponding to the effective
856 method itself: the translator may instead open-code the effective method's
857 behaviour into each method entry function; and the machinery for handling
858 `delegation chains', such as is used for @|around| methods and primary
859 methods in the standard method combination, is necessarily scattered among
860 a number of small functions.
864 \subsection{Messages with keyword arguments}
865 \label{sec:concepts.methods.keywords}
867 A message or a direct method may declare that it accepts keyword arguments.
868 A message which accepts keyword arguments is called a \emph{keyword message};
869 a direct method which accepts keyword arguments is called a \emph{keyword
872 While method combinations may set their own rules, usually keyword methods
873 can only be defined on keyword messages, and all methods defined on a keyword
874 message must be keyword methods. The direct methods defined on a keyword
875 message may differ in the keywords they accept, both from each other, and
876 from the message. If two applicable methods on the same message both accept
877 a keyword argument with the same name, then these two keyword arguments must
878 also have the same type. Different applicable methods may declare keyword
879 arguments with the same name but different defaults; see below.
881 The keyword arguments acceptable in a message sent to an object are the
882 keywords listed in the message definition, together with all of the keywords
883 accepted by any applicable method. There is no easy way to determine at
884 runtime whether a particular keyword is acceptable in a message to a given
887 At runtime, a direct method which accepts one or more keyword arguments
888 receives an additional argument named @|suppliedp|. This argument is a small
889 structure. For each keyword argument named $k$ accepted by the direct
890 method, @|suppliedp| contains a one-bit-wide bitfield member of type
891 @|unsigned|, also named $k$. If a keyword argument named $k$ was passed in
892 the message, then @|suppliedp.$k$| is one, and $k$ contains the argument
893 value; otherwise @|suppliedp.$k$| is zero, and $k$ contains the default value
894 from the direct method definition if there was one, or an unspecified value
897 %%%--------------------------------------------------------------------------
898 \section{The object lifecycle} \label{sec:concepts.lifecycle}
900 \subsection{Creation} \label{sec:concepts.lifecycle.birth}
902 Construction of a new instance of a class involves three steps.
904 \item \emph{Allocation} arranges for there to be storage space for the
905 instance's slots and associated metadata.
906 \item \emph{Imprinting} fills in the instance's metadata, associating the
907 instance with its class.
908 \item \emph{Initialization} stores appropriate initial values in the
909 instance's slots, and maybe links it into any external data structures as
912 The \descref{SOD_DECL}[macro]{mac} handles constructing instances with
913 automatic storage duration (`on the stack'). Similarly, the
914 \descref{SOD_MAKE}[macro]{mac} and the \descref{sod_make}{fun} and
915 \descref{sod_makev}{fun} functions construct instances allocated from the
916 standard @|malloc| heap. Programmers can add support for other allocation
917 strategies by using the \descref{SOD_INIT}[macro]{mac} and the
918 \descref{sod_init}{fun} and \descref{sod_initv}{fun} functions, which package
919 up imprinting and initialization.
921 \subsubsection{Allocation}
922 Instances of most classes (specifically including those classes defined by
923 Sod itself) can be held in any storage of sufficient size. The in-memory
924 layout of an instance of some class~$C$ is described by the type @|struct
925 $C$__ilayout|, and if the relevant class is known at compile time then the
926 best way to discover the layout size is with the @|sizeof| operator. Failing
927 that, the size required to hold an instance of $C$ is available in a slot in
928 $C$'s class object, as @|$C$__class@->cls.initsz|.
930 It is not in general sufficient to declare, or otherwise allocate, an object
931 of the class type $C$. The class type only describes a single chain of the
932 object's layout. It is nearly always an error to use the class type as if it
933 is a \emph{complete type}, e.g., to declare objects or arrays of the class
934 type, or to enquire about its size or alignment requirements.
936 Instance layouts may be declared as objects with automatic storage duration
937 (colloquially, `allocated on the stack') or allocated dynamically, e.g.,
938 using @|malloc|. They may be included as members of structures or unions, or
939 elements of arrays. Sod's runtime system doesn't retain addresses of
940 instances, so, for example, Sod doesn't make using fancy allocators which
941 sometimes move objects around in memory any more difficult than it needs to
944 There isn't any way to discover the alignment required for a particular
945 class's instances at runtime; it's best to be conservative and assume that
946 the platform's strictest alignment requirement applies.
948 The following simple function correctly allocates and returns space for an
949 instance of a class given a pointer to its class object @<cls>.
951 void *allocate_instance(const SodClass *cls) \\ \ind
952 \{ return malloc(cls@->cls.initsz); \}
955 \subsubsection{Imprinting}
956 Once storage has been allocated, it must be \emph{imprinted} before it can be
957 used as an instance of a class, e.g., before any messages can be sent to it.
959 Imprinting an instance stores some metadata about its direct class in the
960 instance structure, so that the rest of the program (and Sod's runtime
961 library) can tell what sort of object it is, and how to use it.\footnote{%
962 Specifically, imprinting an instance's storage involves storing the
963 appropriate vtable pointers in the right places in it.} %
964 A class object's @|imprint| slot points to a function which will correctly
965 imprint storage for one of that class's instances.
967 Once an instance's storage has been imprinted, it is technically possible to
968 send messages to the instance; however the instance's slots are still
969 uninitialized at this point, so the applicable methods are unlikely to do
970 much of any use unless they've been written specifically for the purpose.
972 The following simple function imprints storage at address @<p> as an instance
973 of a class, given a pointer to its class object @<cls>.
975 void imprint_instance(const SodClass *cls, void *p) \\ \ind
976 \{ cls@->cls.imprint(p); \}
979 \subsubsection{Initialization}
980 The final step for constructing a new instance is to \emph{initialize} it, to
981 establish the necessary invariants for the instance itself and the
982 environment in which it operates.
984 Details of initialization are necessarily class-specific, but typically it
985 involves setting the instance's slots to appropriate values, and possibly
986 linking it into some larger data structure to keep track of it. It is
987 possible for initialization methods to attempt to allocate resources, but
988 this must be done carefully: there is currently no way to report an error
989 from object initialization, so the object must be marked as incompletely
990 initialized, and left in a state where it will be safe to tear down later.
992 Initialization is performed by sending the imprinted instance an @|init|
993 message, defined by the @|SodObject| class. This message uses a nonstandard
994 method combination which works like the standard combination, except that the
995 \emph{default behaviour}, if there is no overriding method, is to initialize
996 the instance's slots, as described below, and to invoke each superclass's
997 initialization fragments. This default behaviour may be invoked multiple
998 times if some method calls on its @|next_method| more than once, unless some
999 other method takes steps to prevent this.
1001 Slots are initialized in a well-defined order.
1003 \item Slots defined by a more specific superclass are initialized after slots
1004 defined by a less specific superclass.
1005 \item Slots defined by the same class are initialized in the order in which
1006 their definitions appear.
1009 A class can define \emph{initialization fragments}: pieces of literal code to
1010 be executed to set up a new instance. Each superclass's initialization
1011 fragments are executed with @|me| bound to an instance pointer of the
1012 appropriate superclass type, immediately after that superclass's slots (if
1013 any) have been initialized; therefore, fragments defined by a more specific
1014 superclass are executed after fragments defined by a less specific
1015 superclass. A class may define more than one initialization fragment: the
1016 fragments are executed in the order in which they appear in the class
1017 definition. It is possible for an initialization fragment to use @|return|
1018 or @|goto| for special control-flow effects, but this is not likely to be a
1021 The @|init| message accepts keyword arguments
1022 (\xref{sec:concepts.methods.keywords}). The set of acceptable keywords is
1023 determined by the applicable methods as usual, but also by the
1024 \emph{initargs} defined by the receiving instance's class and its
1025 superclasses, which are made available to slot initializers and
1026 initialization fragments.
1028 There are two kinds of initarg definitions. \emph{User initargs} are defined
1029 by an explicit @|initarg| item appearing in a class definition: the item
1030 defines a name, type, and (optionally) a default value for the initarg.
1031 \emph{Slot initargs} are defined by attaching an @|initarg| property to a
1032 slot or slot initializer item: the property's value determines the initarg's
1033 name, while the type is taken from the underlying slot type; slot initargs do
1034 not have default values. Both kinds define a \emph{direct initarg} for the
1037 Initargs are inherited. The \emph{applicable} direct initargs for an @|init|
1038 effective method are those defined by the receiving object's class, and all
1039 of its superclasses. Applicable direct initargs with the same name are
1040 merged to form \emph{effective initargs}. An error is reported if two
1041 applicable direct initargs have the same name but different types. The
1042 default value of an effective initarg is taken from the most specific
1043 applicable direct initarg which specifies a defalt value; if no applicable
1044 direct initarg specifies a default value then the effective initarg has no
1047 All initarg values are made available at runtime to user code --
1048 initialization fragments and slot initializer expressions -- through local
1049 variables and a @|suppliedp| structure, as in a direct method
1050 (\xref{sec:concepts.methods.keywords}). Furthermore, slot initarg
1051 definitions influence the initialization of slots.
1053 The process for deciding how to initialize a particular slot works as
1056 \item If there are any slot initargs defined on the slot, or any of its slot
1057 initializers, \emph{and} the sender supplied a value for one or more of the
1058 corresponding effective initargs, then the value of the most specific slot
1059 initarg is stored in the slot.
1060 \item Otherwise, if there are any slot initializers defined which include an
1061 initializer expression, then the initializer expression from the most
1062 specific such slot initializer is evaluated and its value stored in the
1064 \item Otherwise, the slot is left uninitialized.
1066 Note that the default values (if any) of effective initargs do \emph{not}
1067 affect this procedure.
1070 \subsection{Destruction}
1071 \label{sec:concepts.lifecycle.death}
1073 Destruction of an instance, when it is no longer required, consists of two
1076 \item \emph{Teardown} releases any resources held by the instance and
1077 disentangles it from any external data structures.
1078 \item \emph{Deallocation} releases the memory used to store the instance so
1079 that it can be reused.
1081 Teardown alone, for objects which require special deallocation, or for which
1082 deallocation occurs automatically (e.g., instances with automatic storage
1083 duration, or instances whose storage will be garbage-collected), is performed
1084 using the \descref{sod_teardown}[function]{fun}. Destruction of instances
1085 allocated from the standard @|malloc| heap is done using the
1086 \descref{sod_destroy}[function]{fun}.
1088 \subsubsection{Teardown}
1089 Details of teardown are necessarily class-specific, but typically it
1090 involves releasing resources held by the instance, and disentangling it from
1091 any data structures it might be linked into.
1093 Teardown is performed by sending the instance the @|teardown| message,
1094 defined by the @|SodObject| class. The message returns an integer, used as a
1095 boolean flag. If the message returns zero, then the instance's storage
1096 should be deallocated. If the message returns nonzero, then it is safe for
1097 the caller to forget about instance, but should not deallocate its storage.
1098 This is \emph{not} an error return: if some teardown method fails then the
1099 program may be in an inconsistent state and should not continue.
1101 This simple protocol can be used, for example, to implement a reference
1102 counting system, as follows.
1105 class ReferenceCountedObject: SodObject \{ \\ \ind
1106 unsigned nref = 1; \\-
1107 void inc() \{ me@->ref.nref++; \} \\-
1109 int obj.teardown() \\
1111 if (--\,--me@->ref.nref) return (1); \\
1112 else return (CALL_NEXT_METHOD); \-\\
1117 The @|teardown| message uses a nonstandard method combination which works
1118 like the standard combination, except that the \emph{default behaviour}, if
1119 there is no overriding method, is to execute the superclass's teardown
1120 fragments, and to return zero. This default behaviour may be invoked
1121 multiple times if some method calls on its @|next_method| more than once,
1122 unless some other method takes steps to prevent this.
1124 A class can define \emph{teardown fragments}: pieces of literal code to be
1125 executed to shut down an instance. Each superclass's teardown fragments are
1126 executed with @|me| bound to an instance pointer of the appropriate
1127 superclass type; fragments defined by a more specific superclass are executed
1128 before fragments defined by a less specific superclass. A class may define
1129 more than one teardown fragment: the fragments are executed in the order in
1130 which they appear in the class definition. It is possible for an
1131 initialization fragment to use @|return| or @|goto| for special control-flow
1132 effects, but this is not likely to be a good idea. Similarly, it's probably
1133 a better idea to use an @|around| method to influence the return value than
1134 to write an explicit @|return| statement in a teardown fragment.
1136 \subsubsection{Deallocation}
1137 The details of instance deallocation are obviously specific to the allocation
1138 strategy used by the instance, and this is often orthogonal from the object's
1141 The code which makes the decision to destroy an object may often not be aware
1142 of the object's direct class. Low-level details of deallocation often
1143 require the proper base address of the instance's storage, which can be
1144 determined using the \descref{SOD_INSTBASE}[macro]{mac}.
1146 %%%--------------------------------------------------------------------------
1147 \section{Metaclasses} \label{sec:concepts.metaclasses}
1149 In Sod, every object is an instance of some class, and -- unlike, say,
1150 \Cplusplus\ -- classes are proper objects. It follows that, in Sod, every
1151 class~$C$ is itself an instance of some class~$M$, which is called $C$'s
1152 \emph{metaclass}. Metaclass instances are usually constructed statically, at
1153 compile time, and marked read-only.
1155 As an added complication, Sod classes, and other metaobjects such as
1156 messages, methods, slots and so on, also have classes \emph{at translation
1157 time}. These translation-time metaclasses are not Sod classes; they are CLOS
1158 classes, implemented in Common Lisp.
1161 \subsection{Runtime metaclasses}
1162 \label{sec:concepts.metaclasses.runtime}
1164 Like other classes, metaclasses can declare messages, and define slots and
1165 methods. Slots defined by the metaclass are called \emph{class slots}, as
1166 opposed to \emph{instance slots}. Similarly, messages and methods defined by
1167 the metaclass are termed \emph{class messages} and \emph{class methods}
1168 respectively, though these are used much less frequently.
1170 \subsubsection{The braid}
1171 Every object is an instance of some class. There are only finitely many
1177 \node[lit] (obj) {SodObject};
1178 \node[lit] (cls) [right=10mm of obj] {SodClass};
1179 \draw [->, dashed] (obj) to[bend right] (cls);
1180 \draw [->] (cls) to[bend right] (obj);
1181 \draw [->, dashed] (cls) to[loop right] (cls);
1184 \fbox{\ \begin{tikzpicture}
1185 \node (subclass) {subclass of};
1186 \node (instance) [below=\jot of subclass] {instance of};
1187 \draw [->] ($(subclass.west) - (10mm, 0)$) -- ++(8mm, 0);
1188 \draw [->, dashed] ($(instance.west) - (10mm, 0)$) -- ++(8mm, 0);
1190 \caption{The Sod braid} \label{fig:concepts.metaclasses.braid}
1193 Consider the directed graph whose nodes are classes, and where there is an
1194 arc from $C$ to $D$ if and only if $C$ is an instance of $D$. There are only
1195 finitely many nodes. Every node has an arc leaving it, because every object
1196 -- and hence every class -- is an instance of some class. Therefore this
1197 graph must contain at least one cycle.
1199 In Sod, this situation is resolved in the simplest manner possible:
1200 @|SodClass| is the only predefined metaclass, and it is an instance of
1201 itself. The only other predefined class is @|SodObject|, which is also an
1202 instance of @|SodClass|. There is exactly one root class, namely
1203 @|SodObject|; consequently, @|SodClass| is a direct subclass of @|SodObject|.
1205 \Xref{fig:concepts.metaclasses.braid} shows a diagram of this situation.
1207 \subsubsection{Class slots and initializers}
1208 Instance initializers were described in \xref{sec:concepts.classes.slots}. A
1209 class can also define \emph{class initializers}, which provide values for
1210 slots defined by its metaclass. The initial value for a class slot is
1211 determined as follows.
1213 \item Nonstandard slot classes may be initialized by custom Lisp code. For
1214 example, all of the slots defined by @|SodClass| are of this kind. User
1215 initializers are not permitted for such slots.
1216 \item If the class or any of its superclasses defines a class initializer for
1217 the slot, then the class initializer defined by the most specific such
1219 \item Otherwise, if the metaclass or one of its superclasses defines an
1220 instance initializer, then the instance initializer defined by he most
1221 specific such class is used.
1222 \item Otherwise there is no initializer, and an error will be reported.
1224 Initializers for class slots must be constant expressions (for scalar slots)
1225 or aggregate initializers containing constant expressions.
1227 \subsubsection{Metaclass selection and consistency}
1228 Sod enforces a \emph{metaclass consistency rule}: if $C$ has metaclass $M$,
1229 then any subclass $C$ must have a metaclass which is a subclass of $M$.
1231 The definition of a new class can name the new class's metaclass explicitly,
1232 by defining a @|metaclass| property; the Sod translator will verify that the
1233 choice of metaclass is acceptable.
1235 If no @|metaclass| property is given, then the translator will select a
1236 default metaclass as follows. Let $C_1$, $C_2$, \dots, $C_n$ be the direct
1237 superclasses of the new class, and let $M_1$, $M_2$, \dots, $M_n$ be their
1238 respective metaclasses (not necessarily distinct). If there exists exactly
1239 one minimal metaclass $M_i$, i.e., there exists an $i$, with $1 \le i \le n$,
1240 such that $M_i$ is a subclass of every $M_j$, for $1 \le j \le n$, then $M_i$
1241 is selected as the new class's metaclass. Otherwise the situation is
1242 ambiguous and an error will be reported. Usually, the ambiguity can be
1243 resolved satisfactorily by defining a new class $M^*$ as a direct subclass of
1247 \subsection{Translation-time metaobjects}
1248 \label{sec:concepts.metaclasses.compile-time}
1254 %%%--------------------------------------------------------------------------
1255 \section{Compatibility considerations} \label{sec:concepts.compatibility}
1257 Sod doesn't make source-level compatibility especially difficult. As long as
1258 classes, slots, and messages don't change names or dissappear, and slots and
1259 messages retain their approximate types, everything will be fine.
1261 Binary compatibility is much more difficult. Unfortunately, Sod classes have
1262 rather fragile binary interfaces.\footnote{%
1263 Research suggestion: investigate alternative instance and vtable layouts
1264 which improve binary compatibility, probably at the expense of instance
1265 compactness, and efficiency of slot access and message sending. There may
1266 be interesting trade-offs to be made.} %
1268 If instances are allocated \fixme{incomplete}
1270 %%%----- That's all, folks --------------------------------------------------
1272 %%% Local variables:
1274 %%% TeX-master: "sod.tex"