Commit | Line | Data |
---|---|---|
62f9852b MW |
1 | %%% -*-latex-*- |
2 | %%% | |
3 | %%% The runtime library | |
4 | %%% | |
5 | %%% (c) 2015 Straylight/Edgeware | |
6 | %%% | |
7 | ||
8 | %%%----- Licensing notice --------------------------------------------------- | |
9 | %%% | |
10 | %%% This file is part of the Simple Object Definition system. | |
11 | %%% | |
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. | |
16 | %%% | |
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. | |
21 | %%% | |
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. | |
25 | ||
26 | \chapter{The runtime library} \label{ch:runtime} | |
27 | ||
e520bc24 MW |
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}. | |
31 | ||
32 | %%%-------------------------------------------------------------------------- | |
9e91c8e7 MW |
33 | \section{Keyword argument support} \label{sec:runtime.keywords} |
34 | ||
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}. | |
38 | ||
39 | ||
40 | \subsection{Type definitions} \label{sec:sec:runtime.keywords.types} | |
41 | ||
42 | The header file defines two simple structure types, and a function type which | |
43 | will be described later. | |
44 | ||
45 | \begin{describe}[struct kwval]{type} | |
020b9e2b MW |
46 | {struct kwval \{ \\ \ind |
47 | const char *kw; \\ | |
48 | const void *val; \-\\ | |
9e91c8e7 MW |
49 | \};} |
50 | ||
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.) | |
56 | \end{describe} | |
57 | ||
58 | \begin{describe}[struct kwtab]{type} | |
020b9e2b MW |
59 | {struct kwtab \{ \\ \ind |
60 | const struct kwval *v; \\ | |
61 | size_t n; \-\\ | |
9e91c8e7 MW |
62 | \};} |
63 | ||
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. | |
67 | \end{describe} | |
68 | ||
69 | ||
70 | \subsection{Calling functions with keyword arguments} | |
71 | \label{sec:runtime.keywords.calling} | |
72 | ||
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}. | |
78 | ||
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. | |
86 | ||
87 | That said, the underlying machinery is presented first, and the convenience | |
88 | macros are described later. | |
89 | ||
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. | |
96 | ||
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 | |
101 | ||
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. | |
111 | ||
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. | |
117 | ||
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. | |
125 | ||
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. | |
129 | ||
130 | \end{description} | |
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. | |
134 | ||
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. | |
138 | ||
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. | |
143 | ||
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. | |
148 | \end{describe} | |
149 | ||
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. | |
153 | ||
154 | This is unnecessary with compilers which support C99 or later, since once | |
155 | can use @|KWARGS()| with an empty @<body> argument. | |
156 | \end{describe} | |
157 | ||
158 | The following keyword-argument macros can be used within the @|KWARGS| | |
159 | @<body> argument. | |
160 | ||
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. | |
165 | \end{describe} | |
166 | ||
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. | |
170 | \end{describe} | |
171 | ||
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 | |
175 | vector. | |
176 | \end{describe} | |
177 | ||
178 | ||
179 | \subsection{Defining functions with keyword arguments} | |
180 | \label{sec:runtime.keywords.defining} | |
181 | ||
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 | |
781a8fbd | 186 | plan to add some later, do not define a keyword set; instead, use the |
9e91c8e7 MW |
187 | @|KWPARSE_EMPTY| macro described below.) |
188 | ||
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. | |
196 | ||
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, | |
781a8fbd MW |
199 | conventionally named @`_'. It should expand to a sequence of one or more |
200 | list items of the form | |
9e91c8e7 MW |
201 | \begin{prog} |
202 | _(@<type>, @<name>, @<default>) | |
203 | \end{prog} | |
781a8fbd | 204 | with no separation between them. For example: |
9e91c8e7 | 205 | \begin{prog} |
5e4a5d53 MW |
206 | \#define example_KWSET(_) \macsl \\ \ind |
207 | _(int, x, 0) \macsl \\ | |
9e91c8e7 MW |
208 | _(const char *, y, NULL) |
209 | \end{prog} | |
210 | ||
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). | |
214 | ||
215 | Each @<type> should be a C @<type-name> such that | |
216 | \begin{prog} | |
217 | @<type> @<name> ; | |
218 | \end{prog} | |
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. | |
223 | ||
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.) | |
228 | ||
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. | |
232 | ||
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.) | |
239 | ||
240 | Specifically, the macro declares a mandatory argument @|const char | |
241 | *kwfirst_| (to collect the first keyword name), and a variable-length | |
242 | argument tail. | |
243 | ||
244 | The \descref{KWPARSE}[macro]{mac} assumes that the enclosing function's | |
245 | argument list ends with a @|KWTAIL| marker. | |
246 | \end{describe} | |
247 | ||
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 | |
257 | declarations. | |
258 | \end{describe} | |
259 | ||
260 | \subsubsection{Auxiliary definitions} | |
261 | The following macros define data types and functions used for collecting | |
262 | keyword arguments. | |
263 | ||
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|. | |
270 | \end{describe} | |
271 | ||
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 | |
781a8fbd MW |
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. | |
9e91c8e7 MW |
280 | \end{describe} |
281 | ||
282 | \begin{describe}[KWSET_PARSEFN]{mac} | |
283 | {@<declaration-specifiers> KWSET_PARSEFN(@<set>)} | |
284 | ||
285 | The macro @|KWSET_PARSEFN| defines a keyword argument \emph{parser | |
286 | function} | |
287 | \begin{prog} | |
020b9e2b MW |
288 | void @<set>{}_kwparse% |
289 | (\=struct @<set>{}_kwargs *@<kw>, | |
290 | const char *@<kwfirst>, va_list *@<ap>, \+\\ | |
291 | const struct kwval *@<v>, size_t @<n>); | |
9e91c8e7 MW |
292 | \end{prog} |
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 | |
295 | name.\footnote{% | |
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.} % | |
299 | ||
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. | |
306 | ||
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>.) | |
314 | ||
5b0c3a98 | 315 | The variable-argument tail is read from the list described by @|*@<ap>|. |
9e91c8e7 MW |
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; | |
02840f3d | 331 | otherwise, the cursor object @|*@<ap>| will be modified as the function |
9e91c8e7 MW |
332 | extracts successive arguments from the tail. |
333 | ||
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. | |
337 | ||
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. | |
341 | \end{describe} | |
342 | ||
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. | |
346 | ||
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 | |
352 | char~*|. | |
353 | ||
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). | |
360 | ||
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> | |
365 | appropriately. | |
366 | \end{describe} | |
367 | ||
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}. | |
376 | ||
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. | |
388 | \end{describe} | |
389 | ||
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. | |
397 | ||
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. | |
401 | ||
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). | |
408 | ||
409 | The effect is to check that the argument tail contains no keyword arguments | |
410 | other than the special predefined ones. | |
411 | \end{describe} | |
412 | ||
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}. | |
418 | \end{describe} | |
419 | ||
420 | \begin{describe}[kw_parseempty]{fun} | |
020b9e2b MW |
421 | {void kw_parseempty% |
422 | (\=const char *@<set>, | |
423 | const char *@<kwfirst>, va_list *@<ap>, \+\\ | |
424 | const struct kwval *@<v>, size_t @<n>);} | |
9e91c8e7 MW |
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}). | |
428 | ||
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}. | |
434 | \end{describe} | |
435 | ||
436 | \subsection{Function wrappers} \label{sec:runtime.keywords.wrappers} | |
437 | ||
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. | |
449 | ||
450 | A few macros are provided to make this task easier. | |
451 | ||
452 | \begin{describe}[KW_COUNT]{mac}{KW_COUNT(@<set>)} | |
453 | Returns the number of keywords defined in a keyword set named @<set>. | |
454 | \end{describe} | |
455 | ||
456 | \begin{describe}[KW_COPY]{mac} | |
457 | {KW_COPY(@<fromset>, @<toset>, @<kw>, @<v>, @<n>);} | |
458 | ||
459 | The macro @|KW_COPY| populates a vector of @|kwval| structures from a | |
460 | keyword-argument structure. | |
461 | ||
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 | |
468 | type. | |
469 | ||
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| | |
476 | member. | |
477 | ||
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. | |
481 | \end{describe} | |
482 | ||
483 | ||
484 | \subsection{Handling unknown-keyword errors} | |
485 | \label{sec:runtime.keywords.unknown} | |
486 | ||
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. | |
492 | ||
493 | In this situation, the parser functions generated by | |
494 | \descref{KWSET_PARSEFN}{mac} (and the \descref{kw_parseempty}[function]{fun}) | |
495 | call @|kw_unknown|. | |
496 | ||
497 | \begin{describe}[kw_unknown]{fun} | |
498 | {void kw_unknown(const char *@<set>, const char *@<kw>);} | |
499 | ||
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. | |
505 | ||
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}. | |
509 | \end{describe} | |
510 | ||
511 | \begin{describe}[kw_unkhookfn]{type} | |
512 | {typedef void kw_unkhookfn(const char *@<set>, const char *@<kw>);} | |
513 | ||
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. | |
518 | \end{describe} | |
519 | ||
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 | |
531 | such efforts.} % | |
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. | |
535 | ||
536 | Initially, this variable points to the | |
537 | \descref{kw_defunknown}[function]{fun}. | |
538 | \end{describe} | |
539 | ||
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}. | |
545 | ||
546 | This function is the default value of the \descref{kw_unkhook}[hook | |
547 | variable]{var}. | |
548 | \end{describe} | |
549 | ||
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. | |
553 | ||
554 | \begin{prog} | |
555 | \#define KWARGS_TEST(k, val) KWARGS(K(k, val) K(kw.unknown, 0)) | |
020b9e2b | 556 | \\+ |
9e91c8e7 | 557 | static jmp_buf kw_test_jmp; |
020b9e2b MW |
558 | \\+ |
559 | static void kw_test_unknown(const char *set, const char *kw) \\ | |
560 | \{ \\ \ind | |
561 | if (strcmp(kw, "kw.unknown")) longjmp(kw_test_jmp, 1); \\ | |
562 | else longjmp(kw_test_jmp, 2); \-\\ | |
563 | \} \\+ | |
564 | ||
5e4a5d53 MW |
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\-\\ | |
573 | \} \macsl \\ | |
574 | kw_unkhook = oldunk; \macsl\-\\ | |
020b9e2b MW |
575 | \} while (0) \\+ |
576 | ||
577 | @/* Example of use */ \\ | |
578 | int f; \\ | |
9e91c8e7 | 579 | KW_TEST(f, somefunc(1, "two", 3, KWARGS_TEST("shiny", 68.7))); \\ |
888d5e58 | 580 | /\=* \comment{now @|f| is nonzero if @|somefunc| accepts the |
020b9e2b MW |
581 | @|shiny| keyword} \+\\ |
582 | {}* \comment{(which we hope wants a @|double| argument)} \\ | |
9e91c8e7 MW |
583 | {}*/ |
584 | \end{prog} | |
585 | ||
586 | %%%-------------------------------------------------------------------------- | |
e520bc24 MW |
587 | \section{Object system support} \label{sec:runtime.object} |
588 | ||
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 | |
591 | objects. | |
62f9852b MW |
592 | |
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. | |
597 | ||
e520bc24 | 598 | |
4e3a7cb2 | 599 | \subsection{Layout utilities} \label{sec:runtime.object.layout} |
e520bc24 | 600 | |
4e3a7cb2 MW |
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. | |
62f9852b MW |
605 | |
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 | |
609 | general use. | |
610 | ||
62f9852b | 611 | \begin{describe}[SOD_OFFSETDIFF]{mac} |
09efeb89 | 612 | {ptrdiff_t SOD_OFFSETDIFF(@<type>, @<member>_1, @<member>_2);} |
62f9852b MW |
613 | Returns the signed offset between two members of a structure or union type. |
614 | ||
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>. | |
619 | ||
620 | This macro is used internally when generating vtables and is not expected | |
621 | to be very useful elsewhere. | |
622 | \end{describe} | |
623 | ||
624 | \begin{describe}[SOD_ILAYOUT]{mac} | |
09efeb89 | 625 | {@<cls>{}__ilayout *SOD_ILAYOUT(@<cls>, @<chead>, const void *@<obj>);} |
62f9852b MW |
626 | Recovers the instance layout base address from a pointer to one of its |
627 | instance chains. | |
628 | ||
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 | |
634 | @<obj>. | |
635 | ||
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. | |
640 | \end{describe} | |
641 | ||
62f9852b MW |
642 | \begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @<cls> *@<obj>)} |
643 | Finds the base address of an instance's layout. | |
644 | ||
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. | |
648 | ||
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. | |
652 | \end{describe} | |
653 | ||
62f9852b | 654 | |
4e3a7cb2 | 655 | \subsection{Classes} \label{sec:runtime.object.class} |
62f9852b | 656 | |
4e3a7cb2 MW |
657 | The following macros and functions query the runtime relationships between |
658 | instances and classes. | |
62f9852b | 659 | |
4e3a7cb2 MW |
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. | |
62f9852b | 663 | |
4e3a7cb2 MW |
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|.) | |
62f9852b MW |
668 | \end{describe} |
669 | ||
62f9852b | 670 | \begin{describe}[sod_subclassp]{fun} |
0ed1c8a9 | 671 | {int sod_subclassp(const SodClass *@<sub>, const SodClass *@<super>);} |
62f9852b MW |
672 | |
673 | Decide whether one class @<sub> is actually a subclass of another class | |
674 | @<super>. | |
675 | ||
676 | The @<sod_subclassp> function returns nonzero if and only if | |
677 | @<sub> is a subclass of @<super>. | |
678 | ||
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. | |
681 | \end{describe} | |
682 | ||
4e3a7cb2 MW |
683 | |
684 | \subsection{Conversions} \label{sec:runtime.object.conversions} | |
685 | ||
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 | |
688 | instance. | |
689 | ||
690 | \begin{describe}[SOD_XCHAIN]{mac} | |
691 | {void *SOD_CHAIN(@<chead>, const @<cls> *@<obj>);} | |
692 | Performs a `cross-chain upcast'. | |
693 | ||
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.) | |
699 | ||
700 | This macro is used by the generated @|@<cls>{}__CONV_@<c>| conversion | |
701 | macros, which you are encouraged to use instead where possible. | |
702 | \end{describe} | |
703 | ||
704 | \begin{describe*} | |
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 | |
62f9852b MW |
710 | pointers. |
711 | ||
4e3a7cb2 MW |
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. | |
715 | ||
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. | |
62f9852b MW |
718 | |
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 | |
4e3a7cb2 MW |
723 | they're much faster and can't fail. |
724 | ||
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 | |
728 | the correct type. | |
729 | \end{describe*} | |
730 | ||
731 | ||
732 | \subsection{Instance lifecycle} | |
733 | \label{sec:runtime.object.lifecycle} | |
734 | ||
735 | The following macros and functions manage the standard steps along an | |
736 | instance's lifecycle. | |
737 | ||
a142609c MW |
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. | |
742 | ||
743 | \begin{describe*} | |
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>. | |
752 | ||
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. | |
755 | ||
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>. | |
762 | ||
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}. | |
768 | \end{describe*} | |
769 | ||
a42893dd MW |
770 | \begin{describe}[sod_teardown]{fun}{int sod_teardown(void *@<p>);} |
771 | Tears down an instance of a class, releasing any resources it holds. | |
772 | ||
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} | |
776 | for details. | |
777 | \end{describe} | |
778 | ||
4e3a7cb2 MW |
779 | \subsubsection{Automatic storage duration} |
780 | The following macro constructs an instance with automatic storage duration. | |
781 | ||
a142609c | 782 | \begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>, @<keywords>);} |
4e3a7cb2 MW |
783 | Declares and initializes an instance with automatic storage duration. |
784 | ||
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 | |
789 | initial values. | |
790 | ||
a142609c MW |
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}. | |
794 | ||
4e3a7cb2 | 795 | The instance has automatic storage duration: pointers to it will become |
a42893dd MW |
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}. | |
799 | \end{describe} | |
800 | ||
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. | |
805 | ||
806 | \begin{describe*} | |
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>. | |
812 | ||
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. | |
815 | ||
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>. | |
822 | ||
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}. | |
827 | ||
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. | |
831 | \end{describe*} | |
832 | ||
833 | \begin{describe}[sod_destroy]{fun}{int sod_destroy(void *@<p>);} | |
834 | Tears down and frees an instance allocated using @|malloc|. | |
835 | ||
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. | |
62f9852b MW |
841 | \end{describe} |
842 | ||
843 | %%%----- That's all, folks -------------------------------------------------- | |
844 | ||
845 | %%% Local variables: | |
846 | %%% mode: LaTeX | |
847 | %%% TeX-master: "sod.tex" | |
848 | %%% TeX-PDF-mode: t | |
849 | %%% End: |