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}. An
67 object's state is maintained in named \emph{slots}, each of which can store a
68 C value of an appropriate (scalar or aggregate) type. An object's behaviour
69 is stimulated by sending it \emph{messages}. A message has a name, and may
70 carry a number of arguments, which are C values; sending a message may result
71 in the state of receiving object (or other objects) being changed, and a C
72 value being returned to the sender.
74 Every object is a (direct) instance of some \emph{class}. The class
75 determines which slots its instances have, which messages its instances can
76 be sent, and which methods are invoked when those messages are received. The
77 Sod translator's main job is to read class definitions and convert them into
78 appropriate C declarations, tables, and functions. An object cannot
79 (usually) change its direct class, and the direct class of an object is not
80 affected by, for example, the static type of a pointer to it.
83 \subsection{Superclasses and inheritance}
84 \label{sec:concepts.classes.inherit}
86 \subsubsection{Class relationships}
87 Each class has zero or more \emph{direct superclasses}.
89 A class with no direct superclasses is called a \emph{root class}. The Sod
90 runtime library includes a root class named @|SodObject|; making new root
91 classes is somewhat tricky, and won't be discussed further here.
93 Classes can have more than one direct superclass, i.e., Sod supports
94 \emph{multiple inheritance}. A Sod class definition for a class~$C$ lists
95 the direct superclasses of $C$ in a particular order. This order is called
96 the \emph{local precedence order} of $C$, and the list which consists of $C$
97 follows by $C$'s direct superclasses in local precedence order is called the
98 $C$'s \emph{local precedence list}.
100 The multiple inheritance in Sod works similarly to multiple inheritance in
101 Lisp-like languages, such as Common Lisp, EuLisp, Dylan, and Python, which is
102 very different from how multiple inheritance works in \Cplusplus.\footnote{%
103 The latter can be summarized as `badly'. By default in \Cplusplus, an
104 instance receives an additional copy of superclass's state for each path
105 through the class graph from the instance's direct class to that
106 superclass, though this behaviour can be overridden by declaring
107 superclasses to be @|virtual|. Also, \Cplusplus\ offers only trivial
108 method combination (\xref{sec:concepts.methods}), leaving programmers to
109 deal with delegation manually and (usually) statically.} %
111 If $C$ is a class, then the \emph{superclasses} of $C$ are
113 \item $C$ itself, and
114 \item the superclasses of each of $C$'s direct superclasses.
116 The \emph{proper superclasses} of a class $C$ are the superclasses of $C$
117 except for $C$ itself. If a class $B$ is a (direct, proper) superclass of
118 $C$, then $C$ is a \emph{(direct, proper) subclass} of $B$. If $C$ is a root
119 class then the only superclass of $C$ is $C$ itself, and $C$ has no proper
122 If an object is a direct instance of class~$C$ then the object is also an
123 (indirect) instance of every superclass of $C$.
125 If $C$ has a proper superclass $B$, then $B$ must not have $C$ as a direct
126 superclass. In different terms, if we construct a graph, whose vertices are
127 classes, and draw an edge from each class to each of its direct superclasses,
128 then this graph must be acyclic. In yet other terms, the `is a superclass
129 of' relation is a partial order on classes.
131 \subsubsection{The class precedence list}
132 This partial order is not quite sufficient for our purposes. For each class
133 $C$, we shall need to extend it into a total order on $C$'s superclasses.
134 This calculation is called \emph{superclass linearization}, and the result is
135 a \emph{class precedence list}, which lists each of $C$'s superclasses
136 exactly once. If a superclass $B$ precedes (resp.\ follows) some other
137 superclass $A$ in $C$'s class precedence list, then we say that $B$ is a more
138 (resp.\ less) \emph{specific} superclass of $C$ than $A$ is.
140 The superclass linearization algorithm isn't fixed, and extensions to the
141 translator can introduce new linearizations for special effects, but the
142 following properties are expected to hold.
144 \item The first class in $C$'s class precedence list is $C$ itself; i.e.,
145 $C$ is always its own most specific superclass.
146 \item If $A$ and $B$ are both superclasses of $C$, and $A$ is a proper
147 superclass of $B$ then $A$ appears after $B$ in $C$'s class precedence
148 list, i.e., $B$ is a more specific superclass of $C$ than $A$ is.
150 The default linearization algorithm used in Sod is the \emph{C3} algorithm,
151 which has a number of good properties described in~\cite{Barrett:1996:MSL}.
154 \item A \emph{merge} of some number of input lists is a single list
155 containing each item that is in any of the input lists exactly once, and no
156 other items; if an item $x$ appears before an item $y$ in any input list,
157 then $x$ also appears before $y$ in the merge. If a collection of lists
158 have no merge then they are said to be \emph{inconsistent}.
159 \item The class precedence list of a class $C$ is a merge of the local
160 precedence list of $C$ together with the class precedence lists of each of
161 $C$'s direct superclasses.
162 \item If there are no such merges, then the definition of $C$ is invalid.
163 \item Suppose that there are multiple candidate merges. Consider the
164 earliest position in these candidate merges at which they disagree. The
165 \emph{candidate classes} at this position are the classes appearing at this
166 position in the candidate merges. Each candidate class must be a
167 superclass of distinct direct superclasses of $C$, since otherwise the
168 candidates would be ordered by their common subclass's class precedence
169 list. The class precedence list contains, at this position, that candidate
170 class whose subclass appears earliest in $C$'s local precedence order.
173 \subsubsection{Class links and chains}
174 The definition for a class $C$ may distinguish one of its proper superclasses
175 as being the \emph{link superclass} for class $C$. Not every class need have
176 a link superclass, and the link superclass of a class $C$, if it exists, need
177 not be a direct superclass of $C$.
179 Superclass links must obey the following rule: if $C$ is a class, then there
180 must be no three distinct superclasses $X$, $Y$ and~$Z$ of $C$ such that $Z$
181 is the link superclass of both $X$ and $Y$. As a consequence of this rule,
182 the superclasses of $C$ can be partitioned into linear \emph{chains}, such
183 that superclasses $A$ and $B$ are in the same chain if and only if one can
184 trace a path from $A$ to $B$ by following superclass links, or \emph{vice
187 Since a class links only to one of its proper superclasses, the classes in a
188 chain are naturally ordered from most- to least-specific. The least specific
189 class in a chain is called the \emph{chain head}; the most specific class is
190 the \emph{chain tail}. Chains are often named after their chain head
194 \label{sec:concepts.classes.names}
196 Classes have a number of other attributes:
198 \item A \emph{name}, which is a C identifier. Class names must be globally
199 unique. The class name is used in the names of a number of associated
200 definitions, to be described later.
201 \item A \emph{nickname}, which is also a C identifier. Unlike names,
202 nicknames are not required to be globally unique. If $C$ is any class,
203 then all the superclasses of $C$ must have distinct nicknames.
207 \subsection{Slots} \label{sec:concepts.classes.slots}
209 Each class defines a number of \emph{slots}. Much like a structure member, a
210 slot has a \emph{name}, which is a C identifier, and a \emph{type}. Unlike
211 many other object systems, different superclasses of a class $C$ can define
212 slots with the same name without ambiguity, since slot references are always
213 qualified by the defining class's nickname.
215 \subsubsection{Slot initializers}
216 As well as defining slot names and types, a class can also associate an
217 \emph{initial value} with each slot defined by itself or one of its
218 subclasses. A class $C$ provides an \emph{initialization message} (see
219 \xref{sec:concepts.lifecycle.birth}, and \xref{sec:structures.root.sodclass})
220 whose methods set the slots of a \emph{direct} instance of the class to the
221 correct initial values. If several of $C$'s superclasses define initializers
222 for the same slot then the initializer from the most specific such class is
223 used. If none of $C$'s superclasses define an initializer for some slot then
224 that slot will be left uninitialized.
226 The initializer for a slot with scalar type may be any C expression. The
227 initializer for a slot with aggregate type must contain only constant
228 expressions if the generated code is expected to be processed by a
229 implementation of C89. Initializers will be evaluated once each time an
230 instance is initialized.
232 Slots are initialized in reverse-precedence order of their defining classes;
233 i.e., slots defined by a less specific superclass are initialized earlier
234 than slots defined by a more specific superclass. Slots defined by the same
235 class are initialized in the order in which they appear in the class
238 The initializer for a slot may refer to other slots in the same object, via
239 the @|me| pointer: in an initializer for a slot defined by a class $C$, @|me|
240 has type `pointer to $C$'. (Note that the type of @|me| depends only on the
241 class which defined the slot, not the class which defined the initializer.)
244 \subsection{C language integration} \label{sec:concepts.classes.c}
246 For each class~$C$, the Sod translator defines a C type, the \emph{class
247 type}, with the same name. This is the usual type used when considering an
248 object as an instance of class~$C$. No entire object will normally have a
249 class type,\footnote{%
250 In general, a class type only captures the structure of one of the
251 superclass chains of an instance. A full instance layout contains multiple
252 chains. See \xref{sec:structures.layout} for the full details.} %
253 so access to instances is almost always via pointers.
255 \subsubsection{Access to slots}
256 The class type for a class~$C$ is actually a structure. It contains one
257 member for each class in $C$'s superclass chain, named with that class's
258 nickname. Each of these members is also a structure, containing the
259 corresponding class's slots, one member per slot. There's nothing special
260 about these slot members: C code can access them in the usual way.
262 For example, if @|MyClass| has the nickname @|mine|, and defines a slot @|x|
263 of type @|int|, then the simple function
265 int get_x(MyClass *m) \{ return (m@->mine.x); \}
267 will extract the value of @|x| from an instance of @|MyClass|.
269 All of this means that there's no such thing as `private' or `protected'
270 slots. If you want to hide implementation details, the best approach is to
271 stash them in a dynamically allocated private structure, and leave a pointer
272 to it in a slot. (This will also help preserve binary compatibility, because
273 the private structure can grow more members as needed. See
274 \xref{sec:concepts.compatibility} for more details.)
277 \subsubsection{Sending messages}
278 Sod defines a macro for each message. If a class $C$ defines a message $m$,
279 then the macro is called @|$C$_$m$|. The macro takes a pointer to the
280 receiving object as its first argument, followed by the message arguments, if
281 any, and returns the value returned by the object's effective method for the
282 message (if any). If you have a pointer to an instance of any of $C$'s
283 subclasses, then you can send it the message; it doesn't matter whether the
284 subclass is on the same chain. Note that the receiver argument is evaluated
285 twice, so it's not safe to write a receiver expression which has
288 For example, suppose we defined
291 class Super: SodObject \{ \\ \ind
292 void msg(const char *m); \-\\
294 class Sub: Super \{ \\ \ind
295 void soupy.msg(const char *m)
296 \{ printf("sub sent `\%s'@\\n", m); \} \-\\
299 then we can send the message like this:
301 Sub *sub = /* \dots\ */; \\
302 Super_msg(sub, "hello");
305 What happens under the covers is as follows. The structure pointed to by the
306 instance pointer has a member named @|_vt|, which points to a structure
307 called a `virtual table', or \emph{vtable}, which contains various pieces of
308 information about the object's direct class and layout, and holds pointers to
309 method entries for the messages which the object can receive. The
310 message-sending macro in the example above expands to something similar to
312 sub@->_vt.sub.msg(sub, "Hello");
315 The vtable contains other useful information, such as a pointer to the
316 instance's direct class's \emph{class object} (described below). The full
317 details of the contents and layout of vtables are given in
318 \xref{sec:structures.layout.vtable}.
321 \subsubsection{Class objects}
322 In Sod's object system, classes are objects too. Therefore classes are
323 themselves instances; the class of a class is called a \emph{metaclass}. The
324 consequences of this are explored in \xref{sec:concepts.metaclasses}. The
325 \emph{class object} has the same name as the class, suffixed with
326 `@|__class|'\footnote{%
327 This is not quite true. @|$C$__class| is actually a macro. See
328 \xref{sec:structures.layout.additional} for the gory details.} %
329 and its type is usually @|SodClass|; @|SodClass|'s nickname is @|cls|.
331 A class object's slots contain or point to useful information, tables and
332 functions for working with that class's instances. (The @|SodClass| class
333 doesn't define any messages, so it doesn't have any methods other than for
334 the @|SodObject| lifecycle messages @|init| and @|teardown|; see
335 \xref{sec:concepts.lifecycle}. In Sod, a class slot containing a function
336 pointer is not at all the same thing as a method.)
338 \subsubsection{Conversions}
339 Suppose one has a value of type pointer-to-class-type for some class~$C$, and
340 wants to convert it to a pointer-to-class-type for some other class~$B$.
341 There are three main cases to distinguish.
343 \item If $B$ is a superclass of~$C$, in the same chain, then the conversion
344 is an \emph{in-chain upcast}. The conversion can be performed using the
345 appropriate generated upcast macro (see below), or by simply casting the
346 pointer, using C's usual cast operator (or the \Cplusplus\ @|static_cast<>|
348 \item If $B$ is a superclass of~$C$, in a different chain, then the
349 conversion is a \emph{cross-chain upcast}. The conversion is more than a
350 simple type change: the pointer value must be adjusted. If the direct
351 class of the instance in question is not known, the conversion will require
352 a lookup at runtime to find the appropriate offset by which to adjust the
353 pointer. The conversion can be performed using the appropriate generated
354 upcast macro (see below); the general case is handled by the macro
355 \descref{SOD_XCHAIN}{mac}.
356 \item If $B$ is a subclass of~$C$ then the conversion is a \emph{downcast};
357 otherwise the conversion is a~\emph{cross-cast}. In either case, the
358 conversion can fail: the object in question might not be an instance of~$B$
359 after all. The macro \descref{SOD_CONVERT}{mac} and the function
360 \descref{sod_convert}{fun} perform general conversions. They return a null
361 pointer if the conversion fails. (These are therefore your analogue to the
362 \Cplusplus\ @|dynamic_cast<>| operator.)
364 The Sod translator generates macros for performing both in-chain and
365 cross-chain upcasts. For each class~$C$, and each proper superclass~$B$
366 of~$C$, a macro is defined: given an argument of type pointer to class type
367 of~$C$, it returns a pointer to the same instance, only with type pointer to
368 class type of~$B$, adjusted as necessary in the case of a cross-chain
369 conversion. The macro is named by concatenating
371 \item the name of class~$C$, in upper case,
372 \item the characters `@|__CONV_|', and
373 \item the nickname of class~$B$, in upper case;
375 e.g., if $C$ is named @|MyClass|, and $B$'s name is @|SuperClass| with
376 nickname @|super|, then the macro @|MYCLASS__CONV_SUPER| converts a
377 @|MyClass~*| to a @|SuperClass~*|. See
378 \xref{sec:structures.layout.additional} for the formal description.
380 %%%--------------------------------------------------------------------------
381 \section{Keyword arguments} \label{sec:concepts.keywords}
383 In standard C, the actual arguments provided to a function are matched up
384 with the formal arguments given in the function definition according to their
385 ordering in a list. Unless the (rather cumbersome) machinery for dealing
386 with variable-length argument tails (@|<stdarg.h>|) is used, exactly the
387 correct number of arguments must be supplied, and in the correct order.
389 A \emph{keyword argument} is matched by its distinctive \emph{name}, rather
390 than by its position in a list. Keyword arguments may be \emph{omitted},
391 causing some default behaviour by the function. A function can detect
392 whether a particular keyword argument was supplied: so the default behaviour
393 need not be the same as that caused by any specific value of the argument.
395 Keyword arguments can be provided in three ways.
397 \item Directly, as a variable-length argument tail, consisting (for the most
398 part) of alternating keyword names, as pointers to null-terminated strings,
399 and argument values, and terminated by a null pointer. This is somewhat
400 error-prone, and the support library defines some macros which help ensure
401 that keyword argument lists are well formed.
402 \item Indirectly, through a @|va_list| object capturing a variable-length
403 argument tail passed to some other function. Such indirect argument tails
404 have the same structure as the direct argument tails described above.
405 Because @|va_list| objects are hard to copy, the keyword-argument support
406 library consistently passes @|va_list| objects \emph{by reference}
407 throughout its programming interface.
408 \item Indirectly, through a vector of @|struct kwval| objects, each of which
409 contains a keyword name, as a pointer to a null-terminated string, and the
410 \emph{address} of a corresponding argument value. (This indirection is
411 necessary so that the items in the vector can be of uniform size.)
412 Argument vectors are rather inconvenient to use, but are the only practical
413 way in which a caller can decide at runtime which arguments to include in a
414 call, which is useful when writing wrapper functions.
417 Keyword arguments are provided as a general feature for C functions.
418 However, Sod has special support for messages which accept keyword arguments
419 (\xref{sec:concepts.methods.keywords}); and they play an essential rôle in
420 the instance construction protocol (\xref{sec:concepts.lifecycle.birth}).
422 %%%--------------------------------------------------------------------------
423 \section{Messages and methods} \label{sec:concepts.methods}
425 Objects can be sent \emph{messages}. A message has a \emph{name}, and
426 carries a number of \emph{arguments}. When an object is sent a message, a
427 function, determined by the receiving object's class, is invoked, passing it
428 the receiver and the message arguments. This function is called the
429 class's \emph{effective method} for the message. The effective method can do
430 anything a C function can do, including reading or updating program state or
431 object slots, sending more messages, calling other functions, issuing system
432 calls, or performing I/O; if it finishes, it may return a value, which is
433 returned in turn to the message sender.
435 The set of messages an object can receive, characterized by their names,
436 argument types, and return type, is determined by the object's class. Each
437 class can define new messages, which can be received by any instance of that
438 class. The messages defined by a single class must have distinct names:
439 there is no `function overloading'. As with slots
440 (\xref{sec:concepts.classes.slots}), messages defined by distinct classes are
441 always distinct, even if they have the same names: references to messages are
442 always qualified by the defining class's name or nickname.
444 Messages may take any number of arguments, of any non-array value type.
445 Since message sends are effectively function calls, arguments of array type
446 are implicitly converted to values of the corresponding pointer type. While
447 message definitions may ascribe an array type to an argument, the formal
448 argument will have pointer type, as is usual for C functions. A message may
449 accept a variable-length argument suffix, denoted @|\dots|.
451 A class definition may include \emph{direct methods} for messages defined by
452 it or any of its superclasses.
454 Like messages, direct methods define argument lists and return types, but
455 they may also have a \emph{body}, and a \emph{rôle}.
457 A direct method need not have the same argument list or return type as its
458 message. The acceptable argument lists and return types for a method depend
459 on the message, in particular its method combination
460 (\xref{sec:concepts.methods.combination}), and the method's rôle.
462 A direct method body is a block of C code, and the Sod translator usually
463 defines, for each direct method, a function with external linkage, whose body
464 contains a copy of the direct method body. Within the body of a direct
465 method defined for a class $C$, the variable @|me|, of type pointer to class
466 type of $C$, refers to the receiving object.
469 \subsection{Effective methods and method combinations}
470 \label{sec:concepts.methods.combination}
472 For each message a direct instance of a class might receive, there is a set
473 of \emph{applicable methods}, which are exactly the direct methods defined on
474 the object's class and its superclasses. These direct methods are combined
475 together to form the \emph{effective method} for that particular class and
476 message. Direct methods can be combined into an effective method in
477 different ways, according to the \emph{method combination} specified by the
478 message. The method combination determines which direct method rôles are
479 acceptable, and, for each rôle, the appropriate argument lists and return
482 One direct method, $M$, is said to be more (resp.\ less) \emph{specific} than
483 another, $N$, with respect to a receiving class~$C$, if the class defining
484 $M$ is a more (resp.\ less) specific superclass of~$C$ than the class
487 \subsubsection{The standard method combination}
488 The default method combination is called the \emph{standard method
489 combination}; other method combinations are useful occasionally for special
490 effects. The standard method combination accepts four direct method rôles,
491 called `primary' (the default), @|before|, @|after|, and @|around|.
493 All direct methods subject to the standard method combination must have
494 argument lists which \emph{match} the message's argument list:
496 \item the method's arguments must have the same types as the message, though
497 the arguments may have different names; and
498 \item if the message accepts a variable-length argument suffix then the
499 direct method must instead have a final argument of type @|va_list|.
501 Primary and @|around| methods must have the same return type as the message;
502 @|before| and @|after| methods must return @|void| regardless of the
503 message's return type.
505 If there are no applicable primary methods then no effective method is
506 constructed: the vtables contain null pointers in place of pointers to method
510 \hbox to\hsize{\hss\hbox{\begin{tikzpicture}
511 [order/.append style={color=green!70!black},
512 code/.append style={font=\sffamily},
513 action/.append style={font=\itshape},
514 method/.append style={rectangle, draw=black, thin, fill=blue!30,
515 text height=\ht\strutbox, text depth=\dp\strutbox,
518 \def\delgstack#1#2#3{
519 \node (#10) [method, #2] {#3};
520 \node (#11) [method, above=6mm of #10] {#3};
521 \draw [->] ($(#10.north)!.5!(#10.north west) + (0mm, 1mm)$) --
523 node [code, left=4pt, midway] {next_method};
524 \draw [<-] ($(#10.north)!.5!(#10.north east) + (0mm, 1mm)$) --
526 node [action, right=4pt, midway] {return};
527 \draw [->] ($(#11.north)!.5!(#11.north west) + (0mm, 1mm)$) --
529 node [code, left=4pt, midway] {next_method}
530 node (ld) [above] {$\smash\vdots\mathstrut$};
531 \draw [<-] ($(#11.north)!.5!(#11.north east) + (0mm, 1mm)$) --
533 node [action, right=4pt, midway] {return}
534 node (rd) [above] {$\smash\vdots\mathstrut$};
535 \draw [->] ($(ld.north) + (0mm, 1mm)$) -- ++(0mm, 4mm)
536 node [code, left=4pt, midway] {next_method};
537 \draw [<-] ($(rd.north) + (0mm, 1mm)$) -- ++(0mm, 4mm)
538 node [action, right=4pt, midway] {return};
539 \node (p) at ($(ld.north)!.5!(rd.north)$) {};
540 \node (#1n) [method, above=5mm of p] {#3};
541 \draw [->, order] ($(#10.south east) + (4mm, 1mm)$) --
542 ($(#1n.north east) + (4mm, -1mm)$)
543 node [midway, right, align=left]
544 {Most to \\ least \\ specific};}
546 \delgstack{a}{}{@|around| method}
547 \draw [<-] ($(a0.south)!.5!(a0.south west) - (0mm, 1mm)$) --
549 \draw [->] ($(a0.south)!.5!(a0.south east) - (0mm, 1mm)$) --
551 node [action, right=4pt, midway] {return};
553 \draw [->] ($(an.north)!.6!(an.north west) + (0mm, 1mm)$) --
555 node [code, midway, left=3mm] {next_method}
556 node (b0) [method, above left = 1mm + 4mm and -6mm - 4mm] {};
557 \node (b1) [method] at ($(b0) - (2mm, 2mm)$) {};
558 \node (bn) [method] at ($(b1) - (2mm, 2mm)$) {@|before| method};
559 \draw [->, order] ($(bn.west) - (6mm, 0mm)$) -- ++(12mm, 12mm)
560 node [midway, above left, align=center] {Most to \\ least \\ specific};
561 \draw [->] ($(b0.north east) + (-10mm, 1mm)$) -- ++(8mm, 8mm)
564 \delgstack{m}{above right=1mm and 0mm of an.west |- p}{Primary method}
565 \draw [->] ($(mn.north)!.5!(mn.north west) + (0mm, 1mm)$) -- ++(0mm, 4mm)
566 node [code, left=4pt, midway] {next_method}
567 node [above right = 0mm and -8mm]
568 {$\vcenter{\hbox{\Huge\textcolor{red}{!}}}
569 \vcenter{\hbox{\begin{tabular}[c]{l}
570 \textsf{next_method} \\
574 \draw [->, color=blue, dotted]
575 ($(m0.south)!.2!(m0.south east) - (0mm, 1mm)$) --
576 ($(an.north)!.2!(an.north east) + (0mm, 1mm)$)
577 node [midway, sloped, below] {Return value};
579 \draw [<-] ($(an.north)!.6!(an.north east) + (0mm, 1mm)$) --
581 node [action, midway, right=3mm] {return}
582 node (f0) [method, above right = 1mm and -6mm] {};
583 \node (f1) [method] at ($(f0) + (-2mm, 2mm)$) {};
584 \node (fn) [method] at ($(f1) + (-2mm, 2mm)$) {@|after| method};
585 \draw [<-, order] ($(f0.east) + (6mm, 0mm)$) -- ++(-12mm, 12mm)
586 node [midway, above right, align=center]
587 {Least to \\ most \\ specific};
588 \draw [<-] ($(fn.north west) + (6mm, 1mm)$) -- ++(-8mm, 8mm);
590 \end{tikzpicture}}\hss}
592 \caption{The standard method combination}
593 \label{fig:concepts.methods.stdmeth}
596 The effective method for a message with standard method combination works as
597 follows (see also~\xref{fig:concepts.methods.stdmeth}).
600 \item If any applicable methods have the @|around| rôle, then the most
601 specific such method, with respect to the class of the receiving object, is
604 Within the body of an @|around| method, the variable @|next_method| is
605 defined, having pointer-to-function type. The method may call this
606 function, as described below, any number of times.
608 If there any remaining @|around| methods, then @|next_method| invokes the
609 next most specific such method, returning whichever value that method
610 returns; otherwise the behaviour of @|next_method| is to invoke the
611 @|before| methods (if any), followed by the most specific primary method,
612 followed by the @|after| methods (if any), and to return whichever value
613 was returned by the most specific primary method, as described in the
614 following items. That is, the behaviour of the least specific @|around|
615 method's @|next_method| function is exactly the behaviour that the
616 effective method would have if there were no @|around| methods. Note that
617 if the least-specific @|around| method calls its @|next_method| more than
618 once then the whole sequence of @|before|, primary, and @|after| methods
619 occurs multiple times.
621 The value returned by the most specific @|around| method is the value
622 returned by the effective method.
624 \item If any applicable methods have the @|before| rôle, then they are all
625 invoked, starting with the most specific.
627 \item The most specific applicable primary method is invoked.
629 Within the body of a primary method, the variable @|next_method| is
630 defined, having pointer-to-function type. If there are no remaining less
631 specific primary methods, then @|next_method| is a null pointer.
632 Otherwise, the method may call the @|next_method| function any number of
635 The behaviour of the @|next_method| function, if it is not null, is to
636 invoke the next most specific applicable primary method, and to return
637 whichever value that method returns.
639 If there are no applicable @|around| methods, then the value returned by
640 the most specific primary method is the value returned by the effective
641 method; otherwise the value returned by the most specific primary method is
642 returned to the least specific @|around| method, which called it via its
643 own @|next_method| function.
645 \item If any applicable methods have the @|after| rôle, then they are all
646 invoked, starting with the \emph{least} specific. (Hence, the most
647 specific @|after| method is invoked with the most `afterness'.)
651 A typical use for @|around| methods is to allow a base class to set up the
652 dynamic environment appropriately for the primary methods of its subclasses,
653 e.g., by claiming a lock, and releasing it afterwards.
655 The @|next_method| function provided to methods with the primary and
656 @|around| rôles accepts the same arguments, and returns the same type, as the
657 message, except that one or two additional arguments are inserted at the
658 front of the argument list. The first additional argument is always the
659 receiving object, @|me|. If the message accepts a variable argument suffix,
660 then the second addition argument is a @|va_list|; otherwise there is no
661 second additional argument; otherwise, In the former case, a variable
662 @|sod__master_ap| of type @|va_list| is defined, containing a separate copy
663 of the argument pointer (so the method body can process the variable argument
664 suffix itself, and still pass a fresh copy on to the next method).
666 A method with the primary or @|around| rôle may use the convenience macro
667 @|CALL_NEXT_METHOD|, which takes no arguments itself, and simply calls
668 @|next_method| with appropriate arguments: the receiver @|me| pointer, the
669 argument pointer @|sod__master_ap| (if applicable), and the method's
670 arguments. If the method body has overwritten its formal arguments, then
671 @|CALL_NEXT_METHOD| will pass along the updated values, rather than the
674 A primary or @|around| method which invokes its @|next_method| function is
675 said to \emph{extend} the message behaviour; a method which does not invoke
676 its @|next_method| is said to \emph{override} the behaviour. Note that a
677 method may make a decision to override or extend at runtime.
679 \subsubsection{Aggregating method combinations}
680 A number of other method combinations are provided. They are called
681 `aggregating' method combinations because, instead of invoking just the most
682 specific primary method, as the standard method combination does, they invoke
683 the applicable primary methods in turn and aggregate the return values from
686 The aggregating method combinations accept the same four rôles as the
687 standard method combination, and @|around|, @|before|, and @|after| methods
688 work in the same way.
690 The aggregating method combinations provided are as follows.
691 \begin{description} \let\makelabel\code
692 \item[progn] The message must return @|void|. The applicable primary methods
693 are simply invoked in turn, most specific first.
694 \item[sum] The message must return a numeric type.\footnote{%
695 The Sod translator does not check this, since it doesn't have enough
696 insight into @|typedef| names.} %
697 The applicable primary methods are invoked in turn, and their return values
698 added up. The final result is the sum of the individual values.
699 \item[product] The message must return a numeric type. The applicable
700 primary methods are invoked in turn, and their return values multiplied
701 together. The final result is the product of the individual values.
702 \item[min] The message must return a scalar type. The applicable primary
703 methods are invoked in turn. The final result is the smallest of the
705 \item[max] The message must return a scalar type. The applicable primary
706 methods are invoked in turn. The final result is the largest of the
708 \item[and] The message must return a scalar type. The applicable primary
709 methods are invoked in turn. If any method returns zero then the final
710 result is zero and no further methods are invoked. If all of the
711 applicable primary methods return nonzero, then the final result is the
712 result of the last primary method.
713 \item[or] The message must return a scalar type. The applicable primary
714 methods are invoked in turn. If any method returns nonzero then the final
715 result is that nonzero value and no further methods are invoked. If all of
716 the applicable primary methods return zero, then the final result is zero.
719 There is also a @|custom| aggregating method combination, which is described
720 in \xref{sec:fixme.custom-aggregating-method-combination}.
723 \subsection{Method entries} \label{sec:concepts.methods.entry}
725 Each instance is associated with its direct class \fixme{direct instances}
727 The effective methods for each class are determined at translation time, by
728 the Sod translator. For each effective method, one or more \emph{method
729 entry functions} are constructed. A method entry function has three
732 \item It converts the receiver pointer to the correct type. Method entry
733 functions can perform these conversions extremely efficiently: there are
734 separate method entries for each chain of each class which can receive a
735 message, so method entry functions are in the privileged situation of
736 knowing the \emph{exact} class of the receiving object.
737 \item If the message accepts a variable-length argument tail, then two method
738 entry functions are created for each chain of each class: one receives a
739 variable-length argument tail, as intended, and captures it in a @|va_list|
740 object; the other accepts an argument of type @|va_list| in place of the
741 variable-length tail and arranges for it to be passed along to the direct
743 \item It invokes the effective method with the appropriate arguments. There
744 might or might not be an actual function corresponding to the effective
745 method itself: the translator may instead open-code the effective method's
746 behaviour into each method entry function; and the machinery for handling
747 `delegation chains', such as is used for @|around| methods and primary
748 methods in the standard method combination, is necessarily scattered among
749 a number of small functions.
753 \subsection{Messages with keyword arguments}
754 \label{sec:concepts.methods.keywords}
756 A message or a direct method may declare that it accepts keyword arguments.
757 A message which accepts keyword arguments is called a \emph{keyword message};
758 a direct method which accepts keyword arguments is called a \emph{keyword
761 While method combinations may set their own rules, usually keyword methods
762 can only be defined on keyword messages, and all methods defined on a keyword
763 message must be keyword methods. The direct methods defined on a keyword
764 message may differ in the keywords they accept, both from each other, and
765 from the message. If two superclasses of some common class both define
766 keyword methods on the same message, and the methods both accept a keyword
767 argument with the same name, then these two keyword arguments must also have
768 the same type. Different applicable methods may declare keyword arguments
769 with the same name but different defaults; see below.
771 The keyword arguments acceptable in a message sent to an object are the
772 keywords listed in the message definition, together with all of the keywords
773 accepted by any applicable method. There is no easy way to determine at
774 runtime whether a particular keyword is acceptable in a message to a given
777 At runtime, a direct method which accepts one or more keyword arguments
778 receives an additional argument named @|suppliedp|. This argument is a small
779 structure. For each keyword argument named $k$ accepted by the direct
780 method, @|suppliedp| contains a one-bit-wide bitfield member of type
781 @|unsigned|, also named $k$. If a keyword argument named $k$ was passed in
782 the message, then @|suppliedp.$k$| is one, and $k$ contains the argument
783 value; otherwise @|suppliedp.$k$| is zero, and $k$ contains the default value
784 from the direct method definition if there was one, or an unspecified value
787 %%%--------------------------------------------------------------------------
788 \section{The object lifecycle} \label{sec:concepts.lifecycle}
790 \subsection{Creation} \label{sec:concepts.lifecycle.birth}
792 Construction of a new instance of a class involves three steps.
794 \item \emph{Allocation} arranges for there to be storage space for the
795 instance's slots and associated metadata.
796 \item \emph{Imprinting} fills in the instance's metadata, associating the
797 instance with its class.
798 \item \emph{Initialization} stores appropriate initial values in the
799 instance's slots, and maybe links it into any external data structures as
802 The \descref{SOD_DECL}[macro]{mac} handles constructing instances with
803 automatic storage duration (`on the stack'). Similarly, the
804 \descref{SOD_MAKE}[macro]{mac} and the \descref{sod_make}{fun} and
805 \descref{sod_makev}{fun} functions construct instances allocated from the
806 standard @|malloc| heap. Programmers can add support for other allocation
807 strategies by using the \descref{SOD_INIT}[macro]{mac} and the
808 \descref{sod_init}{fun} and \descref{sod_initv}{fun} functions, which package
809 up imprinting and initialization.
811 \subsubsection{Allocation}
812 Instances of most classes (specifically including those classes defined by
813 Sod itself) can be held in any storage of sufficient size. The in-memory
814 layout of an instance of some class~$C$ is described by the type @|struct
815 $C$__ilayout|, and if the relevant class is known at compile time then the
816 best way to discover the layout size is with the @|sizeof| operator. Failing
817 that, the size required to hold an instance of $C$ is available in a slot in
818 $C$'s class object, as @|$C$__class@->cls.initsz|.
820 It is not in general sufficient to declare, or otherwise allocate, an object
821 of the class type $C$. The class type only describes a single chain of the
822 object's layout. It is nearly always an error to use the class type as if it
823 is a \emph{complete type}, e.g., to declare objects or arrays of the class
824 type, or to enquire about its size or alignment requirements.
826 Instance layouts may be declared as objects with automatic storage duration
827 (colloquially, `allocated on the stack') or allocated dynamically, e.g.,
828 using @|malloc|. They may be included as members of structures or unions, or
829 elements of arrays. Sod's runtime system doesn't retain addresses of
830 instances, so, for example, Sod doesn't make using fancy allocators which
831 sometimes move objects around in memory any more difficult than it needs to
834 There isn't any way to discover the alignment required for a particular
835 class's instances at runtime; it's best to be conservative and assume that
836 the platform's strictest alignment requirement applies.
838 The following simple function correctly allocates and returns space for an
839 instance of a class given a pointer to its class object @<cls>.
841 void *allocate_instance(const SodClass *cls) \\ \ind
842 \{ return malloc(cls@->cls.initsz); \}
845 \subsubsection{Imprinting}
846 Once storage has been allocated, it must be \emph{imprinted} before it can be
847 used as an instance of a class, e.g., before any messages can be sent to it.
849 Imprinting an instance stores some metadata about its direct class in the
850 instance structure, so that the rest of the program (and Sod's runtime
851 library) can tell what sort of object it is, and how to use it.\footnote{%
852 Specifically, imprinting an instance's storage involves storing the
853 appropriate vtable pointers in the right places in it.} %
854 A class object's @|imprint| slot points to a function which will correctly
855 imprint storage for one of that class's instances.
857 Once an instance's storage has been imprinted, it is technically possible to
858 send messages to the instance; however the instance's slots are still
859 uninitialized at this point, so the applicable methods are unlikely to do
860 much of any use unless they've been written specifically for the purpose.
862 The following simple function imprints storage at address @<p> as an instance
863 of a class, given a pointer to its class object @<cls>.
865 void imprint_instance(const SodClass *cls, void *p) \\ \ind
866 \{ cls@->cls.imprint(p); \}
869 \subsubsection{Initialization}
870 The final step for constructing a new instance is to \emph{initialize} it, to
871 establish the necessary invariants for the instance itself and the
872 environment in which it operates.
874 Details of initialization are necessarily class-specific, but typically it
875 involves setting the instance's slots to appropriate values, and possibly
876 linking it into some larger data structure to keep track of it. It is
877 possible for initialization methods to attempt to allocate resources, but
878 this must be done carefully: there is currently no way to report an error
879 from object initialization, so the object must be marked as incompletely
880 initialized, and left in a state where it will be safe to tear down later.
882 Initialization is performed by sending the imprinted instance an @|init|
883 message, defined by the @|SodObject| class. This message uses a nonstandard
884 method combination which works like the standard combination, except that the
885 \emph{default behaviour}, if there is no overriding method, is to initialize
886 the instance's slots, as described below, and to invoke each superclass's
887 initialization fragments. This default behaviour may be invoked multiple
888 times if some method calls on its @|next_method| more than once, unless some
889 other method takes steps to prevent this.
891 Slots are initialized in a well-defined order.
893 \item Slots defined by a more specific superclass are initialized after slots
894 defined by a less specific superclass.
895 \item Slots defined by the same class are initialized in the order in which
896 their definitions appear.
899 A class can define \emph{initialization fragments}: pieces of literal code to
900 be executed to set up a new instance. Each superclass's initialization
901 fragments are executed with @|me| bound to an instance pointer of the
902 appropriate superclass type, immediately after that superclass's slots (if
903 any) have been initialized; therefore, fragments defined by a more specific
904 superclass are executed after fragments defined by a less specific
905 superclass. A class may define more than one initialization fragment: the
906 fragments are executed in the order in which they appear in the class
907 definition. It is possible for an initialization fragment to use @|return|
908 or @|goto| for special control-flow effects, but this is not likely to be a
911 The @|init| message accepts keyword arguments
912 (\xref{sec:concepts.methods.keywords}). The set of acceptable keywords is
913 determined by the applicable methods as usual, but also by the
914 \emph{initargs} defined by the receiving instance's class and its
915 superclasses, which are made available to slot initializers and
916 initialization fragments.
918 There are two kinds of initarg definitions. \emph{User initargs} are defined
919 by an explicit @|initarg| item appearing in a class definition: the item
920 defines a name, type, and (optionally) a default value for the initarg.
921 \emph{Slot initargs} are defined by attaching an @|initarg| property to a
922 slot or slot initializer item: the property's value determines the initarg's
923 name, while the type is taken from the underlying slot type; slot initargs do
924 not have default values. Both kinds define a \emph{direct initarg} for the
927 Initargs are inherited. The \emph{applicable} direct initargs for an @|init|
928 effective method are those defined by the receiving object's class, and all
929 of its superclasses. Applicable direct initargs with the same name are
930 merged to form \emph{effective initargs}. An error is reported if two
931 applicable direct initargs have the same name but different types. The
932 default value of an effective initarg is taken from the most specific
933 applicable direct initarg which specifies a defalt value; if no applicable
934 direct initarg specifies a default value then the effective initarg has no
937 All initarg values are made available at runtime to user code --
938 initialization fragments and slot initializer expressions -- through local
939 variables and a @|suppliedp| structure, as in a direct method
940 (\xref{sec:concepts.methods.keywords}). Furthermore, slot initarg
941 definitions influence the initialization of slots.
943 The process for deciding how to initialize a particular slot works as
946 \item If there are any slot initargs defined on the slot, or any of its slot
947 initializers, \emph{and} the sender supplied a value for one or more of the
948 corresponding effective initargs, then the value of the most specific slot
949 initarg is stored in the slot.
950 \item Otherwise, if there are any slot initializers defined which include an
951 initializer expression, then the initializer expression from the most
952 specific such slot initializer is evaluated and its value stored in the
954 \item Otherwise, the slot is left uninitialized.
956 Note that the default values (if any) of effective initargs do \emph{not}
957 affect this procedure.
960 \subsection{Destruction}
961 \label{sec:concepts.lifecycle.death}
963 Destruction of an instance, when it is no longer required, consists of two
966 \item \emph{Teardown} releases any resources held by the instance and
967 disentangles it from any external data structures.
968 \item \emph{Deallocation} releases the memory used to store the instance so
969 that it can be reused.
971 Teardown alone, for objects which require special deallocation, or for which
972 deallocation occurs automatically (e.g., instances with automatic storage
973 duration, or instances whose storage will be garbage-collected), is performed
974 using the \descref{sod_teardown}[function]{fun}. Destruction of instances
975 allocated from the standard @|malloc| heap is done using the
976 \descref{sod_destroy}[function]{fun}.
978 \subsubsection{Teardown}
979 Details of teardown are necessarily class-specific, but typically it
980 involves releasing resources held by the instance, and disentangling it from
981 any data structures it might be linked into.
983 Teardown is performed by sending the instance the @|teardown| message,
984 defined by the @|SodObject| class. The message returns an integer, used as a
985 boolean flag. If the message returns zero, then the instance's storage
986 should be deallocated. If the message returns nonzero, then it is safe for
987 the caller to forget about instance, but should not deallocate its storage.
988 This is \emph{not} an error return: if some teardown method fails then the
989 program may be in an inconsistent state and should not continue.
991 This simple protocol can be used, for example, to implement a reference
992 counting system, as follows.
995 class ReferenceCountedObject: SodObject \{ \\ \ind
996 unsigned nref = 1; \\-
997 void inc() \{ me@->ref.nref++; \} \\-
999 int obj.teardown() \\
1001 if (--\,--me@->ref.nref) return (1); \\
1002 else return (CALL_NEXT_METHOD); \-\\
1007 The @|teardown| message uses a nonstandard method combination which works
1008 like the standard combination, except that the \emph{default behaviour}, if
1009 there is no overriding method, is to execute the superclass's teardown
1010 fragments, and to return zero. This default behaviour may be invoked
1011 multiple times if some method calls on its @|next_method| more than once,
1012 unless some other method takes steps to prevent this.
1014 A class can define \emph{teardown fragments}: pieces of literal code to be
1015 executed to shut down an instance. Each superclass's teardown fragments are
1016 executed with @|me| bound to an instance pointer of the appropriate
1017 superclass type; fragments defined by a more specific superclass are executed
1018 before fragments defined by a less specific superclass. A class may define
1019 more than one teardown fragment: the fragments are executed in the order in
1020 which they appear in the class definition. It is possible for an
1021 initialization fragment to use @|return| or @|goto| for special control-flow
1022 effects, but this is not likely to be a good idea. Similarly, it's probably
1023 a better idea to use an @|around| method to influence the return value than
1024 to write an explicit @|return| statement in a teardown fragment.
1026 \subsubsection{Deallocation}
1027 The details of instance deallocation are obviously specific to the allocation
1028 strategy used by the instance, and this is often orthogonal from the object's
1031 The code which makes the decision to destroy an object may often not be aware
1032 of the object's direct class. Low-level details of deallocation often
1033 require the proper base address of the instance's storage, which can be
1034 determined using the \descref{SOD_INSTBASE}[macro]{mac}.
1036 %%%--------------------------------------------------------------------------
1037 \section{Metaclasses} \label{sec:concepts.metaclasses}
1039 %%%--------------------------------------------------------------------------
1040 \section{Compatibility considerations} \label{sec:concepts.compatibility}
1042 Sod doesn't make source-level compatibility especially difficult. As long as
1043 classes, slots, and messages don't change names or dissappear, and slots and
1044 messages retain their approximate types, everything will be fine.
1046 Binary compatibility is much more difficult. Unfortunately, Sod classes have
1047 rather fragile binary interfaces.\footnote{%
1048 Research suggestion: investigate alternative instance and vtable layouts
1049 which improve binary compatibility, probably at the expense of instance
1050 compactness, and efficiency of slot access and message sending. There may
1051 be interesting trade-offs to be made.} %
1053 If instances are allocated \fixme{incomplete}
1055 %%%----- That's all, folks --------------------------------------------------
1057 %%% Local variables:
1059 %%% TeX-master: "sod.tex"