3 %%% The runtime library
5 %%% (c) 2015 Straylight/Edgeware
8 %%%----- Licensing notice ---------------------------------------------------
10 %%% This file is part of the Simple Object Definition system.
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{The runtime library} \label{ch:runtime}
28 This chapter describes the runtime support macros and functions provided by
29 the Sod library. The common structure of object instances and classes is
30 described in \xref{ch:structures}.
32 %%%--------------------------------------------------------------------------
33 \section{Keyword argument support} \label{sec:runtime.keywords}
35 This section describes the types, macros, and functions exposed in the
36 @|<sod/keyword.h>| header file which provides support for defining and
37 calling functions which make use of keyword arguments; see \xref{sec:concepts.keywords}.
40 \subsection{Type definitions} \label{sec:sec:runtime.keywords.types}
42 The header file defines two simple structure types, and a function type which
43 will be described later.
45 \begin{describe}[struct kwval]{type}
46 {struct kwval \{ \\ \ind
51 The @|kwval| structure describes a keyword argument name/value pair. The
52 @|kw| member points to the name, as a null-terminated string. The @|val|
53 member always contains the \emph{address} of the value. (This somewhat
54 inconvenient arrangement makes the size of a @|kwval| object independent of
55 the actual argument type.)
58 \begin{describe}[struct kwtab]{type}
59 {struct kwtab \{ \\ \ind
60 const struct kwval *v; \\
64 The @|kwtab| structure describes a list of keyword arguments, represented
65 as a vector of @|kwval| structures. The @|v| member points to the start of
66 the vector; the @|n| member contains the number of elements in the vector.
70 \subsection{Calling functions with keyword arguments}
71 \label{sec:runtime.keywords.calling}
73 Functions which accept keyword arguments are ordinary C functions with
74 variable-length argument tails. Hence, they can be called using ordinary C
75 (of the right kind) and all will be well. However, argument lists must
76 follow certain rules (which will be described in full below); failure to do
77 this will result in \emph{undefined behaviour}.
79 The header file provides integration with some C compilers in the form of
80 macros which can be used to help the compiler diagnose errors in calls to
81 keyword-accepting functions; but such support is rather limited at the
82 moment. Some additional macros are provided for use in calls to such
83 functions, and it is recommended that, where possible, these are used. In
84 particular, it's all too easy to forget the trailing null terminator which
85 marks the end of a list of keyword arguments.
87 That said, the underlying machinery is presented first, and the convenience
88 macros are described later.
90 \subsubsection{Keyword argument mechanism}
91 The argument tail, following the mandatory arguments, consists of a sequence
92 of zero or more alternating keyword names, as pointers to null-terminated
93 strings (with type @|const char~*|), and their argument values. This
94 sequence is finally terminated by a null pointer (again with type @|const
95 char~*|) in place of a keyword name.
97 Each function may define for itself which keyword names it accepts,
98 and what types the corresponding argument values should have.
99 There are also (currently) three special keyword names.
100 \begin{description} \let\makelabel\code
102 \item[kw.valist] This special keyword is followed by a pointer to a
103 variable-length argument tail cursor object, of type @|va_list~*|. This
104 cursor object will be modified as the function extracts successive
105 arguments from the tail. The argument tail should consist of alternating
106 keyword names and argument values, as described above, including the first
107 keyword name. (This is therefore different from the convention used when
108 calling keyword argument parser functions: see the description of the
109 \descref{KWSET_PARSEFN}[macro]{mac} for more details about these.) The
110 argument tail may itself contain the special keywords.
112 \item[kw.tab] This special keyword is followed by \emph{two} argument values:
113 a pointer to the base of a vector of @|kwval| structures, and the number of
114 elements in this vector (as a @|size_t|). Each element of the vector
115 describes a single keyword argument: the @|kw| member points to the
116 keyword's name, and the @|val| member points to the value.
118 The vector may contain special keywords. The @|val| pointer for a
119 @|kw.valist| argument should contain the address of an object of type
120 @|va_list~*| (and not point directly to the cursor object, since @|val| is
121 has type @|const void~*| but the cursor will be modified as its argument
122 tail is traversed). The @|val| pointer for a @|kw.tab| argument should
123 contain the address of a @|kwtab| structure which itself contains the base
124 address and length of the argument vector to be processed.
126 \item[kw.unknown] This keyword is never accepted by any function. If it is
127 encountered, the @|kw_unknown| function is called to report the situation
128 as an error; see below.
131 It is possible to construct a circular structure of indirect argument lists
132 (in a number of ways). Don't try to pass such a structure to a function: the
133 result will be unbounded recursion or some other bad outcome.
135 \subsubsection{Argument list structuring macros}
136 The following macros are intended to help with constructing keyword argument
137 lists. Their use is not essential, but may help prevent errors.
139 \begin{describe}[KWARGS]{mac}{KWARGS(@<body>)}
140 The @<body> encloses a sequence of keyword arguments expressed as calls to
141 argument consists of a sequence of calls to the keyword-argument macros
142 described below, one after another without any separation.
144 In C89, macro actual arguments are not permitted to be empty; if there are
145 no keyword arguments to provide, and you're using a C89 compiler, then use
146 @|NO_KWARGS| (below) instead. If your compiler supports C99 or later, it's
147 fine to just write @|KWARGS()| instead.
150 \begin{describe}{mac}{NO_KWARGS}
151 A marker, to be written instead of a @|KWARGS| invocation, to indicate that
152 no keyword arguments are to be passed to a function.
154 This is unnecessary with compilers which support C99 or later, since once
155 can use @|KWARGS()| with an empty @<body> argument.
158 The following keyword-argument macros can be used within the @|KWARGS|
161 \begin{describe}[K]{mac}{K(@<name>, @<value>)}
162 Passes a keyword @<name> and its corresponding @<value>, as a pair of
163 arguments. The @<name> should be a single identifier (not a quoted
164 string). The @<value> may be any C expression of the appropriate type.
167 \begin{describe}[K_VALIST]{mac}{K_VALIST(@<ap>)}
168 Passes an indirect variable-length argument tail. The argument @<ap>
169 should be an lvalue of type @|va_list|, which will be passed by reference.
172 \begin{describe}[K_TAB]{mac}{K_TAB(@<v>, @<n>)}
173 Passes a vector of keyword arguments. The argument @<v> should be the base
174 address of the vector, and @<n> should be the number of elements in the
179 \subsection{Defining functions with keyword arguments}
180 \label{sec:runtime.keywords.defining}
182 \subsubsection{Keyword sets}
183 A \emph{keyword set} defines the collection of keyword arguments accepted by
184 a particular function. The same keyword set may be used by several
185 functions. (If your function currently accepts no keyword arguments, but you
186 plan to add some later, do not define a keyword set; instead, use the
187 @|KWPARSE_EMPTY| macro described below.)
189 Each keyword set has a name, which is a C identifier. It's good to choose
190 meaningful and distinctive names for keyword sets. Keyword set names are
191 meaningful at runtime: they are used as part of the @|kw_unknown| protocol
192 (\xref{sec:runtime.keywords.unknown}), and may be examined by handler
193 functions, or reported to a user in error messages. For a keyword set which
194 is used only by a single function, it is recommended that the set be given
195 the same name as the function.
197 The keyword arguments for a keyword set named @<set> are described by a `list
198 macro' named @|@<set>{}_KWSET|. This macro takes a single argument,
199 conventionally named @`_'. It should expand to a sequence of one or more
200 list items of the form
202 _(@<type>, @<name>, @<default>)
204 with no separation between them. For example:
206 \#define example_KWSET(_) \macsl \\ \ind
207 _(int, x, 0) \macsl \\
208 _(const char *, y, NULL)
211 Each @<name> should be a distinct C identifier; they will be used to name
212 structure members. An argument @<name> should not end with the suffix
213 @`_suppliedp' (for reasons which will soon become apparent).
215 Each @<type> should be a C @<type-name> such that
219 is a valid declaration: so it may consist of declaration specifiers and
220 (possibly qualified) pointer declarator markers, but not array or function
221 markers (since they would have to be placed after the @<name>). This is the
222 same requirement made by the standard \man{va_arg}{3} macro.
224 Each @<default> should be an initializer expression or brace-enclosed list,
225 suitable for use in an aggregate initializer for a variable with automatic
226 storage duration. (In C89, aggregate initializers may contain only constant
227 expressions; this restriction was lifted in C99.)
229 \subsubsection{Function declaration markers}
230 The following marker macros are intended to be used in both declarations and
231 definitions of functions which accept keyword arguments.
233 \begin{describe}{mac}{KWTAIL}
234 The @|KWTAIL| is expected to be used at the end of function parameter type
235 list to indicate that the function accepts keyword arguments; if there are
236 preceding mandatory arguments then the @|KWTAIL| marker should be separated
237 from them with a comma @`,'. (It is permitted for a function parameter
238 type list to contain only a @|KWTAIL| marker.)
240 Specifically, the macro declares a mandatory argument @|const char
241 *kwfirst_| (to collect the first keyword name), and a variable-length
244 The \descref{KWPARSE}[macro]{mac} assumes that the enclosing function's
245 argument list ends with a @|KWTAIL| marker.
248 \begin{describe}{mac}{KWCALL}
249 The @|KWCALL| macro acts as a declaration specifier for functions which
250 accept keyword arguments. Its effect is to arrange for the compiler to
251 check, as far as is possible, that calls to the function are well-formed
252 according to the keyword-argument rules. The exact checking performed
253 depends on the compiler's abilities (and how well supported the compiler
254 is): it may check that every other argument is a string; it may check that
255 the list is terminated with a null pointer; it may not do anything at all.
256 Again, this marker should be included in a function's definition and in any
260 \subsubsection{Auxiliary definitions}
261 The following macros define data types and functions used for collecting
264 \begin{describe}[KWSET_STRUCT]{mac}{KWSET_STRUCT(@<set>);}
265 The @|KWSET_STRUCT| macro defines a \emph{keyword structure} named @|struct
266 @<set>{}_kwargs|. For each argument defined in the keyword set, this
267 structure contains two members: one has exactly the @<name> and @<type>
268 listed in the keyword set definition; the other is a 1-bit-wide bitfield of
269 type @|unsigned int| named @|@<name>{}_suppliedp|.
272 \begin{describe}[KWDECL]{mac}
273 {@<declaration-specifiers> KWDECL(@<set>, @<kw>);}
274 The macro declares and initializes a keyword argument structure variable
275 named @<kw> for the named keyword @<set>. The optional
276 @<declaration-specifiers> may provide additional storage-class specifiers,
277 qualifiers, or other declaration specifiers. The @`_suppliedp' flags are
278 initialized to zero; the other members are initialized with the
279 corresponding defaults from the keyword-set definition.
282 \begin{describe}[KWSET_PARSEFN]{mac}
283 {@<declaration-specifiers> KWSET_PARSEFN(@<set>)}
285 The macro @|KWSET_PARSEFN| defines a keyword argument \emph{parser
288 void @<set>{}_kwparse%
289 (\=struct @<set>{}_kwargs *@<kw>,
290 const char *@<kwfirst>, va_list *@<ap>, \+\\
291 const struct kwval *@<v>, size_t @<n>);
293 The macro call can (and usually will) be preceded by storage class
294 specifiers such as @|static|, for example to adjust the linkage of the
296 I don't recommend declaring parser functions @|inline|: parser functions
297 are somewhat large, and modern compilers are pretty good at figuring out
298 whether to inline static functions.} %
300 The function's behaviour is as follows. It parses keyword arguments from a
301 variable-length argument tail, and/or a vector of @|kwval| structures.
302 When a keyword argument is recognized, for some keyword @<name>, the
303 keyword argument structure pointed to by @<kw> is updated: the flag
304 @|@<name>{}_suppliedp| is set to 1; and the argument value is stored (by
305 simple assignment) in the @<name> member.
307 Hence, if the @`_suppliedp' members are initialized to zero, the caller can
308 determine which keyword arguments were supplied. It is not possible to
309 discover whether two or more arguments have the same keyword: in this case,
310 the value from the last such argument is left in the keyword argument
311 structure, and any values from earlier arguments are lost. (For this
312 purpose, the argument vector @<v> is scanned \emph{after} the
313 variable-length argument tail captured in @<ap>.)
315 The variable-argument tail is read from the list described by @|*@<ap>|.
316 The argument tail is expected to consist of alternating keyword strings (as
317 ordinary null-terminated strings) and the corresponding values, terminated
318 by a null pointer of type @|const char~*| in place of a keyword; except
319 that the first keyword (or terminating null pointer, if no arguments are
320 provided) is expected to have been extracted already and provided as the
321 @<kwfirst> argument; the first argument retrieved using the @|va_list|
322 cursor object should then be the value corresponding to the keyword named
323 by @<kwfirst>.\footnote{%
324 This slightly unusual convention makes it possible for a function to
325 collect the first keyword as a separate mandatory argument, which is
326 essential if there are no other mandatory arguments. It also means that
327 the compiler will emit a diagnostic if you attempt to call a function
328 which expects keyword arguments, but don't supply any and forget the null
329 pointer which terminates the (empty) list.} %
330 If @<kwfirst> is a null pointer, then @<ap> need not be a valid pointer;
331 otherwise, the cursor object @|*@<ap>| will be modified as the function
332 extracts successive arguments from the tail.
334 The keyword vector is read from the vector of @|kwval| structures starting
335 at address @<v> and containing the following @<n> items. If @<n> is zero
336 then @<v> need not be a valid pointer.
338 The function also handles the special @|kw.valist| and @|kw.tab| arguments
339 described above (\xref{sec:runtime.keywords.calling}). If an unrecognized
340 keyword argument is encountered, then \descref{kw_unknown}{fun} is called.
343 \subsubsection{Parsing keywords}
344 The following macros make use of the definitions described above to actually
345 make a function's keyword arguments available to it.
347 \begin{describe}[KW_PARSE]{mac}{KW_PARSE(@<set>, @<kw>, @<kwfirst>);}
348 The @|KW_PARSE| macro invokes a keyword argument parsing function. The
349 @<set> argument should name a keyword set; @<kw> should be an lvalue of
350 type @|struct @<set>{}_kwargs|; and @<kwfirst> should be the name of the
351 enclosing function's last mandatory argument, which must have type @|const
354 It calls the function @|@<set>{}_kwparse| with five arguments: the address
355 of the keyword argument structure @<kw>; the string pointer @<kwfirst>; the
356 address of a temporary argument-tail cursor object of type @|va_list|,
357 constructed on the assumption that @<kwfirst> is the enclosing function's
358 final keyword argument; a null pointer; and the value zero (signifying an
359 empty keyword-argument vector).
361 If the variable @<kw> was declared using \descref{KWDECL}{mac} and the
362 function @|@<set>{}_kwparse| has been defined using
363 \descref{KWSET_PARSEFN}{mac} then the effect is to parse the keyword
364 arguments passed to the function and set the members of @<kw>
368 \begin{describe}[KWPARSE]{mac}{KWPARSE(@<set>);}
369 The macro @|KWPARSE| (note the lack of underscore) combines
370 \descref{KWDECL}{mac} and \descref{KW_PARSE}{mac}. It declares and
371 initializes a keyword argument structure variable with the fixed name
372 @|kw|, and parses the keyword arguments provided to the enclosing function,
373 storing the results in @|kw|. It assumes that the first keyword name is in
374 an argument named @|kwfirst_|, as set up by the
375 \descref{KWTAIL}[marker]{mac}.
377 The macro expands both to a variable declaration and a statement: in C89,
378 declarations must precede statements, so under C89 rules this macro must
379 appear exactly between the declarations at the head of a brace-enclosed
380 block (typically the function body) and the statements at the end. This
381 restriction was lifted in C99, so the macro may appear anywhere in the
382 function body. However, it is recommended that callers avoid taking
383 actions which might require cleanup before attempting to parse their
384 keyword arguments, since keyword argument parsing functions invoke the
385 @|kw_unknown| handler (\xref{sec:runtime.keywords.unknown}) if they
386 encounter an unknown keyword, and the calling function will not get a
387 chance to tidy up after itself if this happens.
390 As mentioned above, it is not permitted to define an empty keyword set.
391 (Specifically, invoking \descref{KWSET_STRUCT}{mac} for an empty keyword set
392 would result in attempting to define a structure with no members, which C
393 doesn't allow.) On the other hand, keyword arguments are a useful extension
394 mechanism, and it's useful to be able to define a function which doesn't
395 currently accept any keywords, but which might in the future be extended to
396 allow keyword arguments.
398 \begin{describe}[KW_PARSE_EMPTY]{mac}{KW_PARSE_EMPTY(@<set>, @<kwfirst>);}
399 This is an analogue to \descref{KW_PARSE}{mac} which checks the keyword
400 argument list for a function which accepts no keyword arguments.
402 It calls the \descref{kw_parseempty}[function]{fun} with five arguments:
403 the @<set> name, as a string; the string pointer @<kwfirst>; the address of
404 a temporary argument-tail cursor object of type @|va_list|, constructed on
405 the assumption that @<kwfirst> is the enclosing function's final keyword
406 argument; a null pointer; and the value zero (signifying an empty
407 keyword-argument vector).
409 The effect is to check that the argument tail contains no keyword arguments
410 other than the special predefined ones.
413 \begin{describe}[KWPARSE_EMPTY]{mac}{KWPARSE_EMPTY(@<set>);}
414 This is an analogue to \descref{KWPARSE}{mac} which checks that the
415 enclosing function has been passed no keyword arguments other than the
416 special predefined ones. It assumes that the first keyword name is in an
417 argument named @|kwfirst_|, as set up by the \descref{KWTAIL}[marker]{mac}.
420 \begin{describe}[kw_parseempty]{fun}
422 (\=const char *@<set>,
423 const char *@<kwfirst>, va_list *@<ap>, \+\\
424 const struct kwval *@<v>, size_t @<n>);}
425 This function checks an keyword argument list to make sure that contains no
426 keyword arguments (other than the special ones described in
427 \xref{sec:runtime.keywords.calling}).
429 The @<set> argument should point to a null-terminated string: this will be
430 reported as the keyword set name to \descref{kw_unknown}{fun}, though it
431 need not (and likely will not) refer to any defined keyword set. The
432 remaining arguments are as for the keyword parsing functions defined by the
433 \descref{KWSET_PARSEFN}[macro]{mac}.
436 \subsection{Function wrappers} \label{sec:runtime.keywords.wrappers}
438 Most users will not need the hairy machinery involving argument vectors.
439 Their main use is in defining \emph{wrapper functions}. Suppose there is a
440 function @<f> which accepts some keyword arguments, and we want to write a
441 function @<g> which accepts the same keywords recognized by @<f> and some
442 additional ones. Unfortunately @<f> may behave differently depending on
443 whether or not a particular keyword argument is supplied at all, but it's not
444 possible to synthesize a valid @|va_list| other than by simply capturing a
445 live argument tail, and it's not possible to decide at runtime whether or not
446 to include some arguments in a function call. It's still possible to write
447 @<g>, by building a vector of keyword arguments, collected one-by-one
448 depending on the corresponding @`_suppliedp' flags.
450 A few macros are provided to make this task easier.
452 \begin{describe}[KW_COUNT]{mac}{KW_COUNT(@<set>)}
453 Returns the number of keywords defined in a keyword set named @<set>.
456 \begin{describe}[KW_COPY]{mac}
457 {KW_COPY(@<fromset>, @<toset>, @<kw>, @<v>, @<n>);}
459 The macro @|KW_COPY| populates a vector of @|kwval| structures from a
460 keyword-argument structure.
462 The @<fromset> and @<toset> arguments should be the names of keyword sets;
463 @<kw> should be an lvalue of type @|@<fromset>{}_kwargs|; @<v> should be
464 the base address of a sufficiently large vector of @|struct kwval| objects;
465 and @<n> should be an lvalue of some appropriate integer type. The
466 @<toset> must be a subset of @<fromset>: i.e., for every keyword defined in
467 @<toset> there is a keyword defined in @<fromset> with the same name and
470 Successive elements of @<v>, starting at index @<n>, are filled in to refer
471 to the keyword arguments defined in @<toset> whose @`_suppliedp' flag is
472 set in the argument structure pointed to by @<kw>; for each such argument,
473 a pointer to the keyword name is stored in the corresponding vector
474 element's @|kw| member, and a pointer to the argument value, held in the
475 keyword argument structure, is stored in the vector element's @|val|
478 At the end of this, the index @<n> is advanced so as to contain the index
479 of the first unused element of @<v>. Hence, at most @|KW_COUNT(@<toset>)|
480 elements of @<v> will be used.
484 \subsection{Handling unknown-keyword errors}
485 \label{sec:runtime.keywords.unknown}
487 When parsing a variable-length argument tail, it is not possible to continue
488 after encountering an unknown keyword name. This is because it is necessary
489 to know the (promoted) type of the following argument value in order to skip
490 past it; but the only clue provided as to the type is the keyword name, which
491 in this case is meaningless.
493 In this situation, the parser functions generated by
494 \descref{KWSET_PARSEFN}{mac} (and the \descref{kw_parseempty}[function]{fun})
497 \begin{describe}[kw_unknown]{fun}
498 {void kw_unknown(const char *@<set>, const char *@<kw>);}
500 This is a function of two arguments: @<set> points to the name of the
501 keyword set expected by the caller, as a null-terminated string; and @<kw>
502 is the unknown keyword which was encountered. All that @|kw_unknown| does
503 is invoke the function whose address is stored in the global variable
504 \descref{kw_unkhook}{var} with the same arguments.
506 This function never returns to its caller: if the @|kw_unkhook| function
507 returns (which it shouldn't) then @|kw_unknown| writes a fatal error
508 message to the standard error stream and calls \man{abort}{3}.
511 \begin{describe}[kw_unkhookfn]{type}
512 {typedef void kw_unkhookfn(const char *@<set>, const char *@<kw>);}
514 The @|kw_unkhookfn| type is the type of unknown-keyword handler functions.
515 A handler function is given two arguments, both of which are pointers to
516 null-terminated strings: @<set> is the name of the keyword set expected;
517 and @<kw> is the name of the offending unknown keyword.
520 \begin{describe}[kw_unkhook]{var}{kw_unkhookfn *kw_unkhook}
521 This variable\footnote{%
522 Having a single global hook variable is obviously inadequate for a modern
523 library, but dealing with multiple threads isn't currently possible
524 without writing (moderately complex) system-specific code which would be
525 out of place in this library. The author's intention is that the hook
526 variable @|kw_unkhook| be `owned' by some external library which can make
527 its functionality available to client programs in a safer and more
528 convenient way. On Unix-like platforms (including Cygwin) that library
529 will be (a later version of) \textbf{mLib}; other platforms will likely
530 need different arrangements. The author is willing to coordinate any
532 holds the current unknown-keyword handler function. It will be invoked by
533 \descref{kw_unknown}{fun}. The function may take whatever action seems
534 appropriate, but should not return to its caller.
536 Initially, this variable points to the
537 \descref{kw_defunknown}[function]{fun}.
540 \begin{describe}[kw_defunknown]{fun}
541 {void kw_defunknown(const char *@<set>, const char *@<kw>);}
542 This function simply writes a message to standard error, to the effect that
543 the keyword named by @<kw> is not known in the keyword set @<set>, and
544 calls \man{abort}{3}.
546 This function is the default value of the \descref{kw_unkhook}[hook
550 As an example of the kind of special effect which can be achieved using this
551 hook, the following hacking answers whether a function recognizes a
552 particular keyword argument.
555 \#define KWARGS_TEST(k, val) KWARGS(K(k, val) K(kw.unknown, 0))
557 static jmp_buf kw_test_jmp;
559 static void kw_test_unknown(const char *set, const char *kw) \\
561 if (strcmp(kw, "kw.unknown")) longjmp(kw_test_jmp, 1); \\
562 else longjmp(kw_test_jmp, 2); \-\\
565 \#define KW_TEST(flag, set, call) do \{ \macsl \\ \ind
566 kw_unkhookfn *oldunk = kw_unkhook; \macsl \\
567 kw_unkhook = kw_test_unknown; \macsl \\
568 switch (setjmp(kw_test_jmp)) \{ \macsl \\ \ind
569 case 0: call; abort(); \macsl \\
570 case 1: flag = 1; break; \macsl \\
571 case 2: flag = 0; break; \macsl \\
572 default: abort(); \macsl\-\\
574 kw_unkhook = oldunk; \macsl\-\\
577 @/* Example of use */ \\
579 KW_TEST(f, somefunc(1, "two", 3, KWARGS_TEST("shiny", 68.7))); \\
580 /\=* \comment{now @|f| is nonzero if @|somefunc| accepts the
581 @|shiny| keyword} \+\\
582 {}* \comment{(which we hope wants a @|double| argument)} \\
586 %%%--------------------------------------------------------------------------
587 \section{Object system support} \label{sec:runtime.object}
589 This section describes the macros and functions exposed in the @|<sod/sod.h>|
590 header file which provide assistance for working with Sod classes and
593 The runtime support functionality defined here generally expects that
594 instances and classes inherit from the standard @|SodObject| root object.
595 While the translator can (at some effort) support alternative roots, they
596 will require different run-time support machinery.
599 \subsection{Layout utilities} \label{sec:runtime.object.layout}
601 The following macros are useful in finding one's way around an instance
602 layout structure, given various levels of information about what kind of
603 object one is dealing with, or for computing the tables which are used for
604 this kind of navigation.
606 These macros are mostly intended for use in code generated by the Sod
607 translator. Others may find them useful for special effects, but they can be
608 tricky to understand and use correctly and can't really be recommended for
611 \begin{describe}[SOD_OFFSETDIFF]{mac}
612 {ptrdiff_t SOD_OFFSETDIFF(@<type>, @<member>_1, @<member>_2);}
613 Returns the signed offset between two members of a structure or union type.
615 Given a structure or union type @<type>, and two member names @<member>_1
616 and @<member>_2, then @|SOD_OFFSETDIFF| gives the difference, in bytes,
617 between the addresses of objects @|$x$.@<member>_1| and @|$x$.@<member>_2|
618 for any object $x$ of type @<type>.
620 This macro is used internally when generating vtables and is not expected
621 to be very useful elsewhere.
624 \begin{describe}[SOD_ILAYOUT]{mac}
625 {@<cls>{}__ilayout *SOD_ILAYOUT(@<cls>, @<chead>, const void *@<obj>);}
626 Recovers the instance layout base address from a pointer to one of its
629 Specifically, given a class name @<cls>, the nickname @<chead> of the least
630 specific class in one of @<cls>'s superclass chains, and a pointer @<obj>
631 to the instance storage for the chain containing @<chead> within a direct
632 instance of @<cls> (i.e., not an instance of any proper subclass),
633 @|SOD_ILAYOUT| returns the a pointer to the layout structure containing
636 This macro is used internally in effective method bodies and is not
637 expected to be very useful elsewhere since it's unusual to have such
638 specific knowledge about the dynamic type of an instance. The
639 @|SOD_INSTBASE| macro (described below) is more suited to general use.
642 \begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @<cls> *@<obj>)}
643 Finds the base address of an instance's layout.
645 Given a pointer @<obj> to an instance, @|SOD_INSTBASE| returns the base
646 address of the storage allocated to @<obj>. This is useful if you want to
647 free a dynamically allocated instance, for example.
649 This macro needs to look up an offset in @<obj>'s vtable to do its work.
650 Compare @|SOD_ILAYOUT| above, which is faster but requires precise
651 knowledge of the instance's dynamic class.
655 \subsection{Classes} \label{sec:runtime.object.class}
657 The following macros and functions query the runtime relationships between
658 instances and classes.
660 \begin{describe}[SOD_CLASSOF]{mac}
661 {const SodClass *SOD_CLASSOF(const @<cls> *@<obj>);}
662 Returns the class object describing an instance's dynamic class.
664 Given a pointer @<obj> to an instance, @|SOD_CLASSOF| returns a pointer to
665 @<obj>'s dynamic class, which (assuming @<obj> is typed correctly in the
666 first place) will be a subclass of @<cls>. (If you wanted the class object
667 for @<cls> itself, it's called @|@<cls>{}__class|.)
670 \begin{describe}[sod_subclassp]{fun}
671 {int sod_subclassp(const SodClass *@<sub>, const SodClass *@<super>);}
673 Decide whether one class @<sub> is actually a subclass of another class
676 The @<sod_subclassp> function returns nonzero if and only if
677 @<sub> is a subclass of @<super>.
679 This involves a run-time trawl through the class structures: while some
680 effort has been made to make it perform well it's still not very fast.
684 \subsection{Conversions} \label{sec:runtime.object.conversions}
686 The following macros and functions are used to convert instance pointers of
687 some (static) type into instance pointers of other static types to the same
690 \begin{describe}[SOD_XCHAIN]{mac}
691 {void *SOD_CHAIN(@<chead>, const @<cls> *@<obj>);}
692 Performs a `cross-chain upcast'.
694 Given a pointer @<obj> to an instance of a class of type @<cls> and the
695 nickname @<chead> of the least specific class in one of @<cls>'s superclass
696 chains which does not contain @<cls> itself, @|SOD_XCHAIN| returns the
697 address of that chain's storage within the instance layout as a raw
698 @|void~*| pointer. (Note that @<cls> is not mentioned explicitly.)
700 This macro is used by the generated @|@<cls>{}__CONV_@<c>| conversion
701 macros, which you are encouraged to use instead where possible.
705 {\dhead[SOD_CONVERT]{mac}
706 {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);}
707 \dhead[sod_convert]{fun}
708 {void *sod_convert(const SodClass *@<cls>, const void *@<obj>);}}
709 Perform general conversions (up-, down-, and cross-casts) on instance
712 Given a class @<cls> and a pointer @<obj> to an instance, return an
713 appropriately converted pointer to @<obj> if @<obj> is indeed an instance
714 of (some subclass of) @<cls>; otherwise return a null pointer.
716 The @|SOD_CONVERT| macro expects @<cls> to be a class name; the
717 @|sod_convert| function expects a pointer to a class object instead.
719 This involves a run-time trawl through the class structures: while some
720 effort has been made to make it perform well it's still not very fast. For
721 upcasts (where @<cls> is a superclass of the static type of @<obj>) the
722 automatically defined conversion macros should be used instead, because
723 they're much faster and can't fail.
725 When the target class is known statically, it's slightly more convenient to
726 use the @|SOD_CONVERT| macro than the @|sod_convert| function, since the
727 class object name is longer and uglier, and the macro returns a pointer of
732 \subsection{Instance lifecycle}
733 \label{sec:runtime.object.lifecycle}
735 The following macros and functions manage the standard steps along an
736 instance's lifecycle.
738 \subsubsection{Low-level operations}
739 The following macros and functions are agnostic with respect to storage
740 allocation strategies. They don't concern themselves with allocation or
741 deallocation, and applications are free to use any suitable mechanism.
744 {\dhead[SOD_INIT]{mac}
745 {@<cls> *SOD_INIT(@<cls>, void *@<p>, @<keywords>);}
746 \dhead[sod_init]{fun}
747 {void *sod_init(const SodClass *@<cls>, void *@<p>, \dots);}
748 \dhead[sod_initv]{fun}
749 {void *sod_initv(const SodClass *@<cls>, void *@<p>, va_list @<ap>);}}
750 Imprints and initializes an instance of a class @<cls> in the storage
751 starting at address~@<p>.
753 The direct class for the new instance is specified as a class name to
754 @|SOD_INIT|, or a pointer to a class object to the functions.
756 Keyword arguments for the initialization message may be provided. The
757 @|SOD_INIT| macro expects a single preprocessor-time argument which is
758 a use of one of \descref{KWARGS}{mac} or \descref{NO_KWARGS}{mac}; the
759 @|sod_init| function expects the keywords as a variable-length argument
760 tail; and @|sod_initv| expects the keywords to be passed indirectly,
761 through the captured argument-tail cursor @<ap>.
763 The return value is an instance pointer for the class @<cls>; the
764 @|SOD_INIT| macro will have converted it to the correct type, so it should
765 probably be used where possible. In fact, this is guaranteed to be equal
766 to @<p> by the layout rules described in
767 \xref{sec:structures.layout.instance}.
770 \begin{describe}[sod_teardown]{fun}{int sod_teardown(void *@<p>);}
771 Tears down an instance of a class, releasing any resources it holds.
773 This function is a very thin wrapper around sending the @|obj.teardown|
774 message. See the description of that message
775 (page~\pageref{msg:obj.teardown}) and \xref{sec:concepts.lifecycle.death}
779 \subsubsection{Automatic storage duration}
780 The following macro constructs an instance with automatic storage duration.
782 \begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>, @<keywords>);}
783 Declares and initializes an instance with automatic storage duration.
785 Given a class name @<cls> and an identifier @<var>, @|SOD_DECL| declares
786 @<var> to be a pointer to an instance of @<cls>. The instance is
787 initialized in the sense that its vtable and class pointers have been set
788 up, and slots for which initializers are defined are set to the appropriate
791 Keyword arguments for the initialization message may be provided. The
792 macro expects a single preprocessor-time argument which is a use of one of
793 \descref{KWARGS}{mac} or \descref{NO_KWARGS}{mac}.
795 The instance has automatic storage duration: pointers to it will become
796 invalid when control exits the scope of the declaration. If necessary, the
797 instance should be torn down before this happens, using the
798 \descref{sod_teardown}[function]{fun}.
801 \subsubsection{Dynamic allocation}
802 The following macros and functions deal with objects allocated from the
803 standard C heap. They don't work in freestanding implementations where
804 @|malloc| and @|free| are not available.
807 {\dhead[SOD_MAKE]{mac}{@<cls> *SOD_MAKE(@<cls>, @<keywords>);}
808 \dhead[sod_make]{fun}{void *sod_make(const SodClass *@<cls>, \dots);}
809 \dhead[sod_makev]{fun}
810 {void *sod_makev(const SodClass *@<cls>, va_list @<ap>);}}
811 Constructs and returns a pointer to a new instance of @<cls>.
813 The direct class for the new instance is specified as a class name to
814 @|SOD_MAKE|, or a class object to the functions.
816 Keyword arguments for the initialization message may be provided. The
817 @|SOD_MAKE| macro expects a single preprocessor-time argument which is
818 a use of one of \descref{KWARGS}{mac} or \descref{NO_KWARGS}{mac}; the
819 @|sod_make| function expects the keywords as a variable-length argument
820 tail; and @|sod_makev| expects the keywords to be passed indirectly,
821 through the captured argument-tail cursor @<ap>.
823 Storage for the new instance will have been allocated using the standard
824 @|malloc| function. The easiest way to destroy the instance, when it is no
825 longer needed, is probably to call the
826 \descref{sod_destroy}[function]{fun}.
828 The return value is an instance pointer for the class @<cls>; the
829 @|SOD_MAKE| macro will have converted it to the correct type, so it should
830 probably be used where possible.
833 \begin{describe}[sod_destroy]{fun}{int sod_destroy(void *@<p>);}
834 Tears down and frees an instance allocated using @|malloc|.
836 The pointer @<p> should be an instance pointer, i.e., a pointer to any of
837 an instance's chains. The instance is torn down, by sending it the
838 \descref{obj.teardown}[message]{msg}. If the instance reports itself ready
839 for deallocation, then its storage is released using @|free|. The return
840 value is the value returned by the @|obj.teardown| message.
843 %%%----- That's all, folks --------------------------------------------------
847 %%% TeX-master: "sod.tex"