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} | |
46 | {struct kwval \{ \\ \ind | |
47 | const char *kw; \\ | |
48 | const void *val; \- \\ | |
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} | |
59 | {struct kwtab \{ \\ \ind | |
60 | const struct kwval *v; \\ | |
61 | size_t n; \- \\ | |
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 MW |
205 | \begin{prog} |
206 | \#define example_KWSET(_) @\\ \\ \ind | |
207 | _(int, x, 0) @\\ \\ | |
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} | |
288 | void @<set>{}_kwparse(\=struct @<set>{}_kwargs *@<kw>, | |
289 | const char *@<kwfirst>, va_list *@<ap>, \+ \\ | |
290 | const struct kwval *@<v>, size_t @<n>); | |
291 | \end{prog} | |
292 | The macro call can (and usually will) be preceded by storage class | |
293 | specifiers such as @|static|, for example to adjust the linkage of the | |
294 | name.\footnote{% | |
295 | I don't recommend declaring parser functions @|inline|: parser functions | |
296 | are somewhat large, and modern compilers are pretty good at figuring out | |
297 | whether to inline static functions.} % | |
298 | ||
299 | The function's behaviour is as follows. It parses keyword arguments from a | |
300 | variable-length argument tail, and/or a vector of @|kwval| structures. | |
301 | When a keyword argument is recognized, for some keyword @<name>, the | |
302 | keyword argument structure pointed to by @<kw> is updated: the flag | |
303 | @|@<name>{}_suppliedp| is set to 1; and the argument value is stored (by | |
304 | simple assignment) in the @<name> member. | |
305 | ||
306 | Hence, if the @`_suppliedp' members are initialized to zero, the caller can | |
307 | determine which keyword arguments were supplied. It is not possible to | |
308 | discover whether two or more arguments have the same keyword: in this case, | |
309 | the value from the last such argument is left in the keyword argument | |
310 | structure, and any values from earlier arguments are lost. (For this | |
311 | purpose, the argument vector @<v> is scanned \emph{after} the | |
312 | variable-length argument tail captured in @<ap>.) | |
313 | ||
5b0c3a98 | 314 | The variable-argument tail is read from the list described by @|*@<ap>|. |
9e91c8e7 MW |
315 | The argument tail is expected to consist of alternating keyword strings (as |
316 | ordinary null-terminated strings) and the corresponding values, terminated | |
317 | by a null pointer of type @|const char~*| in place of a keyword; except | |
318 | that the first keyword (or terminating null pointer, if no arguments are | |
319 | provided) is expected to have been extracted already and provided as the | |
320 | @<kwfirst> argument; the first argument retrieved using the @|va_list| | |
321 | cursor object should then be the value corresponding to the keyword named | |
322 | by @<kwfirst>.\footnote{% | |
323 | This slightly unusual convention makes it possible for a function to | |
324 | collect the first keyword as a separate mandatory argument, which is | |
325 | essential if there are no other mandatory arguments. It also means that | |
326 | the compiler will emit a diagnostic if you attempt to call a function | |
327 | which expects keyword arguments, but don't supply any and forget the null | |
328 | pointer which terminates the (empty) list.} % | |
329 | If @<kwfirst> is a null pointer, then @<ap> need not be a valid pointer; | |
330 | otherwise, the cursor object @|* @<ap>| will be modified as the function | |
331 | extracts successive arguments from the tail. | |
332 | ||
333 | The keyword vector is read from the vector of @|kwval| structures starting | |
334 | at address @<v> and containing the following @<n> items. If @<n> is zero | |
335 | then @<v> need not be a valid pointer. | |
336 | ||
337 | The function also handles the special @|kw.valist| and @|kw.tab| arguments | |
338 | described above (\xref{sec:runtime.keywords.calling}). If an unrecognized | |
339 | keyword argument is encountered, then \descref{kw_unknown}{fun} is called. | |
340 | \end{describe} | |
341 | ||
342 | \subsubsection{Parsing keywords} | |
343 | The following macros make use of the definitions described above to actually | |
344 | make a function's keyword arguments available to it. | |
345 | ||
346 | \begin{describe}[KW_PARSE]{mac}{KW_PARSE(@<set>, @<kw>, @<kwfirst>);} | |
347 | The @|KW_PARSE| macro invokes a keyword argument parsing function. The | |
348 | @<set> argument should name a keyword set; @<kw> should be an lvalue of | |
349 | type @|struct @<set>{}_kwargs|; and @<kwfirst> should be the name of the | |
350 | enclosing function's last mandatory argument, which must have type @|const | |
351 | char~*|. | |
352 | ||
353 | It calls the function @|@<set>{}_kwparse| with five arguments: the address | |
354 | of the keyword argument structure @<kw>; the string pointer @<kwfirst>; the | |
355 | address of a temporary argument-tail cursor object of type @|va_list|, | |
356 | constructed on the assumption that @<kwfirst> is the enclosing function's | |
357 | final keyword argument; a null pointer; and the value zero (signifying an | |
358 | empty keyword-argument vector). | |
359 | ||
360 | If the variable @<kw> was declared using \descref{KWDECL}{mac} and the | |
361 | function @|@<set>{}_kwparse| has been defined using | |
362 | \descref{KWSET_PARSEFN}{mac} then the effect is to parse the keyword | |
363 | arguments passed to the function and set the members of @<kw> | |
364 | appropriately. | |
365 | \end{describe} | |
366 | ||
367 | \begin{describe}[KWPARSE]{mac}{KWPARSE(@<set>);} | |
368 | The macro @|KWPARSE| (note the lack of underscore) combines | |
369 | \descref{KWDECL}{mac} and \descref{KW_PARSE}{mac}. It declares and | |
370 | initializes a keyword argument structure variable with the fixed name | |
371 | @|kw|, and parses the keyword arguments provided to the enclosing function, | |
372 | storing the results in @|kw|. It assumes that the first keyword name is in | |
373 | an argument named @|kwfirst_|, as set up by the | |
374 | \descref{KWTAIL}[marker]{mac}. | |
375 | ||
376 | The macro expands both to a variable declaration and a statement: in C89, | |
377 | declarations must precede statements, so under C89 rules this macro must | |
378 | appear exactly between the declarations at the head of a brace-enclosed | |
379 | block (typically the function body) and the statements at the end. This | |
380 | restriction was lifted in C99, so the macro may appear anywhere in the | |
381 | function body. However, it is recommended that callers avoid taking | |
382 | actions which might require cleanup before attempting to parse their | |
383 | keyword arguments, since keyword argument parsing functions invoke the | |
384 | @|kw_unknown| handler (\xref{sec:runtime.keywords.unknown}) if they | |
385 | encounter an unknown keyword, and the calling function will not get a | |
386 | chance to tidy up after itself if this happens. | |
387 | \end{describe} | |
388 | ||
389 | As mentioned above, it is not permitted to define an empty keyword set. | |
390 | (Specifically, invoking \descref{KWSET_STRUCT}{mac} for an empty keyword set | |
391 | would result in attempting to define a structure with no members, which C | |
392 | doesn't allow.) On the other hand, keyword arguments are a useful extension | |
393 | mechanism, and it's useful to be able to define a function which doesn't | |
394 | currently accept any keywords, but which might in the future be extended to | |
395 | allow keyword arguments. | |
396 | ||
397 | \begin{describe}[KW_PARSE_EMPTY]{mac}{KW_PARSE_EMPTY(@<set>, @<kwfirst>);} | |
398 | This is an analogue to \descref{KW_PARSE}{mac} which checks the keyword | |
399 | argument list for a function which accepts no keyword arguments. | |
400 | ||
401 | It calls the \descref{kw_parseempty}[function]{fun} with five arguments: | |
402 | the @<set> name, as a string; the string pointer @<kwfirst>; the address of | |
403 | a temporary argument-tail cursor object of type @|va_list|, constructed on | |
404 | the assumption that @<kwfirst> is the enclosing function's final keyword | |
405 | argument; a null pointer; and the value zero (signifying an empty | |
406 | keyword-argument vector). | |
407 | ||
408 | The effect is to check that the argument tail contains no keyword arguments | |
409 | other than the special predefined ones. | |
410 | \end{describe} | |
411 | ||
412 | \begin{describe}[KWPARSE_EMPTY]{mac}{KWPARSE_EMPTY(@<set>);} | |
413 | This is an analogue to \descref{KWPARSE}{mac} which checks that the | |
414 | enclosing function has been passed no keyword arguments other than the | |
415 | special predefined ones. It assumes that the first keyword name is in an | |
416 | argument named @|kwfirst_|, as set up by the \descref{KWTAIL}[marker]{mac}. | |
417 | \end{describe} | |
418 | ||
419 | \begin{describe}[kw_parseempty]{fun} | |
420 | {void kw_parseempty(\=const char *@<set>, | |
421 | const char *@<kwfirst>, va_list *@<ap>, \+ \\ | |
422 | const struct kwval *@<v>, size_t @<n>);} | |
423 | This function checks an keyword argument list to make sure that contains no | |
424 | keyword arguments (other than the special ones described in | |
425 | \xref{sec:runtime.keywords.calling}). | |
426 | ||
427 | The @<set> argument should point to a null-terminated string: this will be | |
428 | reported as the keyword set name to \descref{kw_unknown}{fun}, though it | |
429 | need not (and likely will not) refer to any defined keyword set. The | |
430 | remaining arguments are as for the keyword parsing functions defined by the | |
431 | \descref{KWSET_PARSEFN}[macro]{mac}. | |
432 | \end{describe} | |
433 | ||
434 | \subsection{Function wrappers} \label{sec:runtime.keywords.wrappers} | |
435 | ||
436 | Most users will not need the hairy machinery involving argument vectors. | |
437 | Their main use is in defining \emph{wrapper functions}. Suppose there is a | |
438 | function @<f> which accepts some keyword arguments, and we want to write a | |
439 | function @<g> which accepts the same keywords recognized by @<f> and some | |
440 | additional ones. Unfortunately @<f> may behave differently depending on | |
441 | whether or not a particular keyword argument is supplied at all, but it's not | |
442 | possible to synthesize a valid @|va_list| other than by simply capturing a | |
443 | live argument tail, and it's not possible to decide at runtime whether or not | |
444 | to include some arguments in a function call. It's still possible to write | |
445 | @<g>, by building a vector of keyword arguments, collected one-by-one | |
446 | depending on the corresponding @`_suppliedp' flags. | |
447 | ||
448 | A few macros are provided to make this task easier. | |
449 | ||
450 | \begin{describe}[KW_COUNT]{mac}{KW_COUNT(@<set>)} | |
451 | Returns the number of keywords defined in a keyword set named @<set>. | |
452 | \end{describe} | |
453 | ||
454 | \begin{describe}[KW_COPY]{mac} | |
455 | {KW_COPY(@<fromset>, @<toset>, @<kw>, @<v>, @<n>);} | |
456 | ||
457 | The macro @|KW_COPY| populates a vector of @|kwval| structures from a | |
458 | keyword-argument structure. | |
459 | ||
460 | The @<fromset> and @<toset> arguments should be the names of keyword sets; | |
461 | @<kw> should be an lvalue of type @|@<fromset>{}_kwargs|; @<v> should be | |
462 | the base address of a sufficiently large vector of @|struct kwval| objects; | |
463 | and @<n> should be an lvalue of some appropriate integer type. The | |
464 | @<toset> must be a subset of @<fromset>: i.e., for every keyword defined in | |
465 | @<toset> there is a keyword defined in @<fromset> with the same name and | |
466 | type. | |
467 | ||
468 | Successive elements of @<v>, starting at index @<n>, are filled in to refer | |
469 | to the keyword arguments defined in @<toset> whose @`_suppliedp' flag is | |
470 | set in the argument structure pointed to by @<kw>; for each such argument, | |
471 | a pointer to the keyword name is stored in the corresponding vector | |
472 | element's @|kw| member, and a pointer to the argument value, held in the | |
473 | keyword argument structure, is stored in the vector element's @|val| | |
474 | member. | |
475 | ||
476 | At the end of this, the index @<n> is advanced so as to contain the index | |
477 | of the first unused element of @<v>. Hence, at most @|KW_COUNT(@<toset>)| | |
478 | elements of @<v> will be used. | |
479 | \end{describe} | |
480 | ||
481 | ||
482 | \subsection{Handling unknown-keyword errors} | |
483 | \label{sec:runtime.keywords.unknown} | |
484 | ||
485 | When parsing a variable-length argument tail, it is not possible to continue | |
486 | after encountering an unknown keyword name. This is because it is necessary | |
487 | to know the (promoted) type of the following argument value in order to skip | |
488 | past it; but the only clue provided as to the type is the keyword name, which | |
489 | in this case is meaningless. | |
490 | ||
491 | In this situation, the parser functions generated by | |
492 | \descref{KWSET_PARSEFN}{mac} (and the \descref{kw_parseempty}[function]{fun}) | |
493 | call @|kw_unknown|. | |
494 | ||
495 | \begin{describe}[kw_unknown]{fun} | |
496 | {void kw_unknown(const char *@<set>, const char *@<kw>);} | |
497 | ||
498 | This is a function of two arguments: @<set> points to the name of the | |
499 | keyword set expected by the caller, as a null-terminated string; and @<kw> | |
500 | is the unknown keyword which was encountered. All that @|kw_unknown| does | |
501 | is invoke the function whose address is stored in the global variable | |
502 | \descref{kw_unkhook}{var} with the same arguments. | |
503 | ||
504 | This function never returns to its caller: if the @|kw_unkhook| function | |
505 | returns (which it shouldn't) then @|kw_unknown| writes a fatal error | |
506 | message to the standard error stream and calls \man{abort}{3}. | |
507 | \end{describe} | |
508 | ||
509 | \begin{describe}[kw_unkhookfn]{type} | |
510 | {typedef void kw_unkhookfn(const char *@<set>, const char *@<kw>);} | |
511 | ||
512 | The @|kw_unkhookfn| type is the type of unknown-keyword handler functions. | |
513 | A handler function is given two arguments, both of which are pointers to | |
514 | null-terminated strings: @<set> is the name of the keyword set expected; | |
515 | and @<kw> is the name of the offending unknown keyword. | |
516 | \end{describe} | |
517 | ||
518 | \begin{describe}[kw_unkhook]{var}{kw_unkhookfn *kw_unkhook} | |
519 | This variable\footnote{% | |
520 | Having a single global hook variable is obviously inadequate for a modern | |
521 | library, but dealing with multiple threads isn't currently possible | |
522 | without writing (moderately complex) system-specific code which would be | |
523 | out of place in this library. The author's intention is that the hook | |
524 | variable @|kw_unkhook| be `owned' by some external library which can make | |
525 | its functionality available to client programs in a safer and more | |
526 | convenient way. On Unix-like platforms (including Cygwin) that library | |
527 | will be (a later version of) \textbf{mLib}; other platforms will likely | |
528 | need different arrangements. The author is willing to coordinate any | |
529 | such efforts.} % | |
530 | holds the current unknown-keyword handler function. It will be invoked by | |
531 | \descref{kw_unknown}{fun}. The function may take whatever action seems | |
532 | appropriate, but should not return to its caller. | |
533 | ||
534 | Initially, this variable points to the | |
535 | \descref{kw_defunknown}[function]{fun}. | |
536 | \end{describe} | |
537 | ||
538 | \begin{describe}[kw_defunknown]{fun} | |
539 | {void kw_defunknown(const char *@<set>, const char *@<kw>);} | |
540 | This function simply writes a message to standard error, to the effect that | |
541 | the keyword named by @<kw> is not known in the keyword set @<set>, and | |
542 | calls \man{abort}{3}. | |
543 | ||
544 | This function is the default value of the \descref{kw_unkhook}[hook | |
545 | variable]{var}. | |
546 | \end{describe} | |
547 | ||
548 | As an example of the kind of special effect which can be achieved using this | |
549 | hook, the following hacking answers whether a function recognizes a | |
550 | particular keyword argument. | |
551 | ||
552 | \begin{prog} | |
553 | \#define KWARGS_TEST(k, val) KWARGS(K(k, val) K(kw.unknown, 0)) | |
554 | \\+ | |
555 | static jmp_buf kw_test_jmp; | |
556 | \\+ | |
557 | static void kw_test_unknown(const char *set, const char *kw) \\ | |
558 | \{ \\ \ind | |
559 | if (strcmp(kw, "kw.unknown")) longjmp(kw_test_jmp, 1); \\ | |
560 | else longjmp(kw_test_jmp, 2); \- \\ | |
561 | \} | |
562 | \\+ | |
563 | \#define KW_TEST(flag, set, call) do \{ @\\ \\ \ind | |
564 | kw_unkhookfn *oldunk = kw_unkhook; @\\ \\ | |
565 | kw_unkhook = kw_test_unknown; @\\ \\ | |
566 | switch (setjmp(kw_test_jmp)) \{ @\\ \\ \ind | |
567 | case 0: call; abort(); @\\ \\ | |
568 | case 1: flag = 1; break; @\\ \\ | |
569 | case 2: flag = 0; break; @\\ \\ | |
570 | default: abort(); \- @\\ \\ | |
571 | \} @\\ \\ | |
572 | kw_unkhook = oldunk; \- @\\ \\ | |
573 | \} while (0) | |
574 | \\+ | |
575 | /* Example of use */ \\ | |
576 | int f; \\ | |
577 | KW_TEST(f, somefunc(1, "two", 3, KWARGS_TEST("shiny", 68.7))); \\ | |
578 | /\=* now f is nonzero if `somefunc' accepts the `shiny' keyword \+ \\ | |
579 | {}* (which we hope wants a double argument) \\ | |
580 | {}*/ | |
581 | \end{prog} | |
582 | ||
583 | %%%-------------------------------------------------------------------------- | |
e520bc24 MW |
584 | \section{Object system support} \label{sec:runtime.object} |
585 | ||
586 | This section describes the macros and functions exposed in the @|<sod/sod.h>| | |
587 | header file which provide assistance for working with Sod classes and | |
588 | objects. | |
62f9852b MW |
589 | |
590 | The runtime support functionality defined here generally expects that | |
591 | instances and classes inherit from the standard @|SodObject| root object. | |
592 | While the translator can (at some effort) support alternative roots, they | |
593 | will require different run-time support machinery. | |
594 | ||
e520bc24 | 595 | |
4e3a7cb2 | 596 | \subsection{Layout utilities} \label{sec:runtime.object.layout} |
e520bc24 | 597 | |
4e3a7cb2 MW |
598 | The following macros are useful in finding one's way around an instance |
599 | layout structure, given various levels of information about what kind of | |
600 | object one is dealing with, or for computing the tables which are used for | |
601 | this kind of navigation. | |
62f9852b MW |
602 | |
603 | These macros are mostly intended for use in code generated by the Sod | |
604 | translator. Others may find them useful for special effects, but they can be | |
605 | tricky to understand and use correctly and can't really be recommended for | |
606 | general use. | |
607 | ||
62f9852b | 608 | \begin{describe}[SOD_OFFSETDIFF]{mac} |
09efeb89 | 609 | {ptrdiff_t SOD_OFFSETDIFF(@<type>, @<member>_1, @<member>_2);} |
62f9852b MW |
610 | Returns the signed offset between two members of a structure or union type. |
611 | ||
612 | Given a structure or union type @<type>, and two member names @<member>_1 | |
613 | and @<member>_2, then @|SOD_OFFSETDIFF| gives the difference, in bytes, | |
614 | between the addresses of objects @|$x$.@<member>_1| and @|$x$.@<member>_2| | |
615 | for any object $x$ of type @<type>. | |
616 | ||
617 | This macro is used internally when generating vtables and is not expected | |
618 | to be very useful elsewhere. | |
619 | \end{describe} | |
620 | ||
621 | \begin{describe}[SOD_ILAYOUT]{mac} | |
09efeb89 | 622 | {@<cls>{}__ilayout *SOD_ILAYOUT(@<cls>, @<chead>, const void *@<obj>);} |
62f9852b MW |
623 | Recovers the instance layout base address from a pointer to one of its |
624 | instance chains. | |
625 | ||
626 | Specifically, given a class name @<cls>, the nickname @<chead> of the least | |
627 | specific class in one of @<cls>'s superclass chains, and a pointer @<obj> | |
628 | to the instance storage for the chain containing @<chead> within a direct | |
629 | instance of @<cls> (i.e., not an instance of any proper subclass), | |
630 | @|SOD_ILAYOUT| returns the a pointer to the layout structure containing | |
631 | @<obj>. | |
632 | ||
633 | This macro is used internally in effective method bodies and is not | |
634 | expected to be very useful elsewhere since it's unusual to have such | |
635 | specific knowledge about the dynamic type of an instance. The | |
636 | @|SOD_INSTBASE| macro (described below) is more suited to general use. | |
637 | \end{describe} | |
638 | ||
62f9852b MW |
639 | \begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @<cls> *@<obj>)} |
640 | Finds the base address of an instance's layout. | |
641 | ||
642 | Given a pointer @<obj> to an instance, @|SOD_INSTBASE| returns the base | |
643 | address of the storage allocated to @<obj>. This is useful if you want to | |
644 | free a dynamically allocated instance, for example. | |
645 | ||
646 | This macro needs to look up an offset in @<obj>'s vtable to do its work. | |
647 | Compare @|SOD_ILAYOUT| above, which is faster but requires precise | |
648 | knowledge of the instance's dynamic class. | |
649 | \end{describe} | |
650 | ||
62f9852b | 651 | |
4e3a7cb2 | 652 | \subsection{Classes} \label{sec:runtime.object.class} |
62f9852b | 653 | |
4e3a7cb2 MW |
654 | The following macros and functions query the runtime relationships between |
655 | instances and classes. | |
62f9852b | 656 | |
4e3a7cb2 MW |
657 | \begin{describe}[SOD_CLASSOF]{mac} |
658 | {const SodClass *SOD_CLASSOF(const @<cls> *@<obj>);} | |
659 | Returns the class object describing an instance's dynamic class. | |
62f9852b | 660 | |
4e3a7cb2 MW |
661 | Given a pointer @<obj> to an instance, @|SOD_CLASSOF| returns a pointer to |
662 | @<obj>'s dynamic class, which (assuming @<obj> is typed correctly in the | |
663 | first place) will be a subclass of @<cls>. (If you wanted the class object | |
664 | for @<cls> itself, it's called @|@<cls>{}__class|.) | |
62f9852b MW |
665 | \end{describe} |
666 | ||
62f9852b | 667 | \begin{describe}[sod_subclassp]{fun} |
0ed1c8a9 | 668 | {int sod_subclassp(const SodClass *@<sub>, const SodClass *@<super>);} |
62f9852b MW |
669 | |
670 | Decide whether one class @<sub> is actually a subclass of another class | |
671 | @<super>. | |
672 | ||
673 | The @<sod_subclassp> function returns nonzero if and only if | |
674 | @<sub> is a subclass of @<super>. | |
675 | ||
676 | This involves a run-time trawl through the class structures: while some | |
677 | effort has been made to make it perform well it's still not very fast. | |
678 | \end{describe} | |
679 | ||
4e3a7cb2 MW |
680 | |
681 | \subsection{Conversions} \label{sec:runtime.object.conversions} | |
682 | ||
683 | The following macros and functions are used to convert instance pointers of | |
684 | some (static) type into instance pointers of other static types to the same | |
685 | instance. | |
686 | ||
687 | \begin{describe}[SOD_XCHAIN]{mac} | |
688 | {void *SOD_CHAIN(@<chead>, const @<cls> *@<obj>);} | |
689 | Performs a `cross-chain upcast'. | |
690 | ||
691 | Given a pointer @<obj> to an instance of a class of type @<cls> and the | |
692 | nickname @<chead> of the least specific class in one of @<cls>'s superclass | |
693 | chains which does not contain @<cls> itself, @|SOD_XCHAIN| returns the | |
694 | address of that chain's storage within the instance layout as a raw | |
695 | @|void~*| pointer. (Note that @<cls> is not mentioned explicitly.) | |
696 | ||
697 | This macro is used by the generated @|@<cls>{}__CONV_@<c>| conversion | |
698 | macros, which you are encouraged to use instead where possible. | |
699 | \end{describe} | |
700 | ||
701 | \begin{describe*} | |
702 | {\dhead[SOD_CONVERT]{mac} | |
703 | {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);} | |
704 | \dhead[sod_convert]{fun} | |
705 | {void *sod_convert(const SodClass *@<cls>, const void *@<obj>);}} | |
706 | Perform general conversions (up-, down-, and cross-casts) on instance | |
62f9852b MW |
707 | pointers. |
708 | ||
4e3a7cb2 MW |
709 | Given a class @<cls> and a pointer @<obj> to an instance, return an |
710 | appropriately converted pointer to @<obj> if @<obj> is indeed an instance | |
711 | of (some subclass of) @<cls>; otherwise return a null pointer. | |
712 | ||
713 | The @|SOD_CONVERT| macro expects @<cls> to be a class name; the | |
714 | @|sod_convert| function expects a pointer to a class object instead. | |
62f9852b MW |
715 | |
716 | This involves a run-time trawl through the class structures: while some | |
717 | effort has been made to make it perform well it's still not very fast. For | |
718 | upcasts (where @<cls> is a superclass of the static type of @<obj>) the | |
719 | automatically defined conversion macros should be used instead, because | |
4e3a7cb2 MW |
720 | they're much faster and can't fail. |
721 | ||
722 | When the target class is known statically, it's slightly more convenient to | |
723 | use the @|SOD_CONVERT| macro than the @|sod_convert| function, since the | |
724 | class object name is longer and uglier, and the macro returns a pointer of | |
725 | the correct type. | |
726 | \end{describe*} | |
727 | ||
728 | ||
729 | \subsection{Instance lifecycle} | |
730 | \label{sec:runtime.object.lifecycle} | |
731 | ||
732 | The following macros and functions manage the standard steps along an | |
733 | instance's lifecycle. | |
734 | ||
a142609c MW |
735 | \subsubsection{Low-level operations} |
736 | The following macros and functions are agnostic with respect to storage | |
737 | allocation strategies. They don't concern themselves with allocation or | |
738 | deallocation, and applications are free to use any suitable mechanism. | |
739 | ||
740 | \begin{describe*} | |
741 | {\dhead[SOD_INIT]{mac} | |
742 | {@<cls> *SOD_INIT(@<cls>, void *@<p>, @<keywords>);} | |
743 | \dhead[sod_init]{fun} | |
744 | {void *sod_init(const SodClass *@<cls>, void *@<p>, \dots);} | |
745 | \dhead[sod_initv]{fun} | |
746 | {void *sod_initv(const SodClass *@<cls>, void *@<p>, va_list @<ap>);}} | |
747 | Imprints and initializes an instance of a class @<cls> in the storage | |
748 | starting at address~@<p>. | |
749 | ||
750 | The direct class for the new instance is specified as a class name to | |
751 | @|SOD_INIT|, or a pointer to a class object to the functions. | |
752 | ||
753 | Keyword arguments for the initialization message may be provided. The | |
754 | @|SOD_INIT| macro expects a single preprocessor-time argument which is | |
755 | a use of one of \descref{KWARGS}{mac} or \descref{NO_KWARGS}{mac}; the | |
756 | @|sod_init| function expects the keywords as a variable-length argument | |
757 | tail; and @|sod_initv| expects the keywords to be passed indirectly, | |
758 | through the captured argument-tail cursor @<ap>. | |
759 | ||
760 | The return value is an instance pointer for the class @<cls>; the | |
761 | @|SOD_INIT| macro will have converted it to the correct type, so it should | |
762 | probably be used where possible. In fact, this is guaranteed to be equal | |
763 | to @<p> by the layout rules described in | |
764 | \xref{sec:structures.layout.instance}. | |
765 | \end{describe*} | |
766 | ||
a42893dd MW |
767 | \begin{describe}[sod_teardown]{fun}{int sod_teardown(void *@<p>);} |
768 | Tears down an instance of a class, releasing any resources it holds. | |
769 | ||
770 | This function is a very thin wrapper around sending the @|obj.teardown| | |
771 | message. See the description of that message | |
772 | (page~\pageref{msg:obj.teardown}) and \xref{sec:concepts.lifecycle.death} | |
773 | for details. | |
774 | \end{describe} | |
775 | ||
4e3a7cb2 MW |
776 | \subsubsection{Automatic storage duration} |
777 | The following macro constructs an instance with automatic storage duration. | |
778 | ||
a142609c | 779 | \begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>, @<keywords>);} |
4e3a7cb2 MW |
780 | Declares and initializes an instance with automatic storage duration. |
781 | ||
782 | Given a class name @<cls> and an identifier @<var>, @|SOD_DECL| declares | |
783 | @<var> to be a pointer to an instance of @<cls>. The instance is | |
784 | initialized in the sense that its vtable and class pointers have been set | |
785 | up, and slots for which initializers are defined are set to the appropriate | |
786 | initial values. | |
787 | ||
a142609c MW |
788 | Keyword arguments for the initialization message may be provided. The |
789 | macro expects a single preprocessor-time argument which is a use of one of | |
790 | \descref{KWARGS}{mac} or \descref{NO_KWARGS}{mac}. | |
791 | ||
4e3a7cb2 | 792 | The instance has automatic storage duration: pointers to it will become |
a42893dd MW |
793 | invalid when control exits the scope of the declaration. If necessary, the |
794 | instance should be torn down before this happens, using the | |
795 | \descref{sod_teardown}[function]{fun}. | |
796 | \end{describe} | |
797 | ||
798 | \subsubsection{Dynamic allocation} | |
799 | The following macros and functions deal with objects allocated from the | |
800 | standard C heap. They don't work in freestanding implementations where | |
801 | @|malloc| and @|free| are not available. | |
802 | ||
803 | \begin{describe*} | |
804 | {\dhead[SOD_MAKE]{mac}{@<cls> *SOD_MAKE(@<cls>, @<keywords>);} | |
805 | \dhead[sod_make]{fun}{void *sod_make(const SodClass *@<cls>, \dots);} | |
806 | \dhead[sod_makev]{fun} | |
807 | {void *sod_makev(const SodClass *@<cls>, va_list @<ap>);}} | |
808 | Constructs and returns a pointer to a new instance of @<cls>. | |
809 | ||
810 | The direct class for the new instance is specified as a class name to | |
811 | @|SOD_MAKE|, or a class object to the functions. | |
812 | ||
813 | Keyword arguments for the initialization message may be provided. The | |
814 | @|SOD_MAKE| macro expects a single preprocessor-time argument which is | |
815 | a use of one of \descref{KWARGS}{mac} or \descref{NO_KWARGS}{mac}; the | |
816 | @|sod_make| function expects the keywords as a variable-length argument | |
817 | tail; and @|sod_makev| expects the keywords to be passed indirectly, | |
818 | through the captured argument-tail cursor @<ap>. | |
819 | ||
820 | Storage for the new instance will have been allocated using the standard | |
821 | @|malloc| function. The easiest way to destroy the instance, when it is no | |
822 | longer needed, is probably to call the | |
823 | \descref{sod_destroy}[function]{fun}. | |
824 | ||
825 | The return value is an instance pointer for the class @<cls>; the | |
826 | @|SOD_MAKE| macro will have converted it to the correct type, so it should | |
827 | probably be used where possible. | |
828 | \end{describe*} | |
829 | ||
830 | \begin{describe}[sod_destroy]{fun}{int sod_destroy(void *@<p>);} | |
831 | Tears down and frees an instance allocated using @|malloc|. | |
832 | ||
833 | The pointer @<p> should be an instance pointer, i.e., a pointer to any of | |
834 | an instance's chains. The instance is torn down, by sending it the | |
835 | \descref{obj.teardown}[message]{msg}. If the instance reports itself ready | |
836 | for deallocation, then its storage is released using @|free|. The return | |
837 | value is the value returned by the @|obj.teardown| message. | |
62f9852b MW |
838 | \end{describe} |
839 | ||
840 | %%%----- That's all, folks -------------------------------------------------- | |
841 | ||
842 | %%% Local variables: | |
843 | %%% mode: LaTeX | |
844 | %%% TeX-master: "sod.tex" | |
845 | %%% TeX-PDF-mode: t | |
846 | %%% End: |