| 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 | |
| 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 | %%%-------------------------------------------------------------------------- |
| 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 |
| 186 | plan to add some later, do not define a keyword set, and use the |
| 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, |
| 199 | conventionally named @`_'. |
| 200 | |
| 201 | It should expand to a sequence of one or more list items of the form |
| 202 | \begin{prog} |
| 203 | _(@<type>, @<name>, @<default>) |
| 204 | \end{prog} |
| 205 | with no separation between them. |
| 206 | |
| 207 | For example: |
| 208 | \begin{prog} |
| 209 | \#define example_KWSET(_) @\\ \\ \ind |
| 210 | _(int, x, 0) @\\ \\ |
| 211 | _(const char *, y, NULL) |
| 212 | \end{prog} |
| 213 | |
| 214 | Each @<name> should be a distinct C identifier; they will be used to name |
| 215 | structure members. An argument @<name> should not end with the suffix |
| 216 | @`_suppliedp' (for reasons which will soon become apparent). |
| 217 | |
| 218 | Each @<type> should be a C @<type-name> such that |
| 219 | \begin{prog} |
| 220 | @<type> @<name> ; |
| 221 | \end{prog} |
| 222 | is a valid declaration: so it may consist of declaration specifiers and |
| 223 | (possibly qualified) pointer declarator markers, but not array or function |
| 224 | markers (since they would have to be placed after the @<name>). This is the |
| 225 | same requirement made by the standard \man{va_arg}{3} macro. |
| 226 | |
| 227 | Each @<default> should be an initializer expression or brace-enclosed list, |
| 228 | suitable for use in an aggregate initializer for a variable with automatic |
| 229 | storage duration. (In C89, aggregate initializers may contain only constant |
| 230 | expressions; this restriction was lifted in C99.) |
| 231 | |
| 232 | \subsubsection{Function declaration markers} |
| 233 | The following marker macros are intended to be used in both declarations and |
| 234 | definitions of functions which accept keyword arguments. |
| 235 | |
| 236 | \begin{describe}{mac}{KWTAIL} |
| 237 | The @|KWTAIL| is expected to be used at the end of function parameter type |
| 238 | list to indicate that the function accepts keyword arguments; if there are |
| 239 | preceding mandatory arguments then the @|KWTAIL| marker should be separated |
| 240 | from them with a comma @`,'. (It is permitted for a function parameter |
| 241 | type list to contain only a @|KWTAIL| marker.) |
| 242 | |
| 243 | Specifically, the macro declares a mandatory argument @|const char |
| 244 | *kwfirst_| (to collect the first keyword name), and a variable-length |
| 245 | argument tail. |
| 246 | |
| 247 | The \descref{KWPARSE}[macro]{mac} assumes that the enclosing function's |
| 248 | argument list ends with a @|KWTAIL| marker. |
| 249 | \end{describe} |
| 250 | |
| 251 | \begin{describe}{mac}{KWCALL} |
| 252 | The @|KWCALL| macro acts as a declaration specifier for functions which |
| 253 | accept keyword arguments. Its effect is to arrange for the compiler to |
| 254 | check, as far as is possible, that calls to the function are well-formed |
| 255 | according to the keyword-argument rules. The exact checking performed |
| 256 | depends on the compiler's abilities (and how well supported the compiler |
| 257 | is): it may check that every other argument is a string; it may check that |
| 258 | the list is terminated with a null pointer; it may not do anything at all. |
| 259 | Again, this marker should be included in a function's definition and in any |
| 260 | declarations. |
| 261 | \end{describe} |
| 262 | |
| 263 | \subsubsection{Auxiliary definitions} |
| 264 | The following macros define data types and functions used for collecting |
| 265 | keyword arguments. |
| 266 | |
| 267 | \begin{describe}[KWSET_STRUCT]{mac}{KWSET_STRUCT(@<set>);} |
| 268 | The @|KWSET_STRUCT| macro defines a \emph{keyword structure} named @|struct |
| 269 | @<set>{}_kwargs|. For each argument defined in the keyword set, this |
| 270 | structure contains two members: one has exactly the @<name> and @<type> |
| 271 | listed in the keyword set definition; the other is a 1-bit-wide bitfield of |
| 272 | type @|unsigned int| named @|@<name>{}_suppliedp|. |
| 273 | \end{describe} |
| 274 | |
| 275 | \begin{describe}[KWDECL]{mac} |
| 276 | {@<declaration-specifiers> KWDECL(@<set>, @<kw>);} |
| 277 | The macro declares and initializes a keyword argument structure variable |
| 278 | named @<kw> for the named keyword @<set>. The optional |
| 279 | @<declaration-specifiers> may provide additional storage-class, qualifiers, |
| 280 | or other declaration specifiers. The @`_suppliedp' flags are initialized |
| 281 | to zero; the other members are initialized with the corresponding defaults |
| 282 | from the keyword-set definition. |
| 283 | \end{describe} |
| 284 | |
| 285 | \begin{describe}[KWSET_PARSEFN]{mac} |
| 286 | {@<declaration-specifiers> KWSET_PARSEFN(@<set>)} |
| 287 | |
| 288 | The macro @|KWSET_PARSEFN| defines a keyword argument \emph{parser |
| 289 | function} |
| 290 | \begin{prog} |
| 291 | void @<set>{}_kwparse(\=struct @<set>{}_kwargs *@<kw>, |
| 292 | const char *@<kwfirst>, va_list *@<ap>, \+ \\ |
| 293 | const struct kwval *@<v>, size_t @<n>); |
| 294 | \end{prog} |
| 295 | The macro call can (and usually will) be preceded by storage class |
| 296 | specifiers such as @|static|, for example to adjust the linkage of the |
| 297 | name.\footnote{% |
| 298 | I don't recommend declaring parser functions @|inline|: parser functions |
| 299 | are somewhat large, and modern compilers are pretty good at figuring out |
| 300 | whether to inline static functions.} % |
| 301 | |
| 302 | The function's behaviour is as follows. It parses keyword arguments from a |
| 303 | variable-length argument tail, and/or a vector of @|kwval| structures. |
| 304 | When a keyword argument is recognized, for some keyword @<name>, the |
| 305 | keyword argument structure pointed to by @<kw> is updated: the flag |
| 306 | @|@<name>{}_suppliedp| is set to 1; and the argument value is stored (by |
| 307 | simple assignment) in the @<name> member. |
| 308 | |
| 309 | Hence, if the @`_suppliedp' members are initialized to zero, the caller can |
| 310 | determine which keyword arguments were supplied. It is not possible to |
| 311 | discover whether two or more arguments have the same keyword: in this case, |
| 312 | the value from the last such argument is left in the keyword argument |
| 313 | structure, and any values from earlier arguments are lost. (For this |
| 314 | purpose, the argument vector @<v> is scanned \emph{after} the |
| 315 | variable-length argument tail captured in @<ap>.) |
| 316 | |
| 317 | The variable-argument tail is read from the list described by @|* @<ap>|. |
| 318 | The argument tail is expected to consist of alternating keyword strings (as |
| 319 | ordinary null-terminated strings) and the corresponding values, terminated |
| 320 | by a null pointer of type @|const char~*| in place of a keyword; except |
| 321 | that the first keyword (or terminating null pointer, if no arguments are |
| 322 | provided) is expected to have been extracted already and provided as the |
| 323 | @<kwfirst> argument; the first argument retrieved using the @|va_list| |
| 324 | cursor object should then be the value corresponding to the keyword named |
| 325 | by @<kwfirst>.\footnote{% |
| 326 | This slightly unusual convention makes it possible for a function to |
| 327 | collect the first keyword as a separate mandatory argument, which is |
| 328 | essential if there are no other mandatory arguments. It also means that |
| 329 | the compiler will emit a diagnostic if you attempt to call a function |
| 330 | which expects keyword arguments, but don't supply any and forget the null |
| 331 | pointer which terminates the (empty) list.} % |
| 332 | If @<kwfirst> is a null pointer, then @<ap> need not be a valid pointer; |
| 333 | otherwise, the cursor object @|* @<ap>| will be modified as the function |
| 334 | extracts successive arguments from the tail. |
| 335 | |
| 336 | The keyword vector is read from the vector of @|kwval| structures starting |
| 337 | at address @<v> and containing the following @<n> items. If @<n> is zero |
| 338 | then @<v> need not be a valid pointer. |
| 339 | |
| 340 | The function also handles the special @|kw.valist| and @|kw.tab| arguments |
| 341 | described above (\xref{sec:runtime.keywords.calling}). If an unrecognized |
| 342 | keyword argument is encountered, then \descref{kw_unknown}{fun} is called. |
| 343 | \end{describe} |
| 344 | |
| 345 | \subsubsection{Parsing keywords} |
| 346 | The following macros make use of the definitions described above to actually |
| 347 | make a function's keyword arguments available to it. |
| 348 | |
| 349 | \begin{describe}[KW_PARSE]{mac}{KW_PARSE(@<set>, @<kw>, @<kwfirst>);} |
| 350 | The @|KW_PARSE| macro invokes a keyword argument parsing function. The |
| 351 | @<set> argument should name a keyword set; @<kw> should be an lvalue of |
| 352 | type @|struct @<set>{}_kwargs|; and @<kwfirst> should be the name of the |
| 353 | enclosing function's last mandatory argument, which must have type @|const |
| 354 | char~*|. |
| 355 | |
| 356 | It calls the function @|@<set>{}_kwparse| with five arguments: the address |
| 357 | of the keyword argument structure @<kw>; the string pointer @<kwfirst>; the |
| 358 | address of a temporary argument-tail cursor object of type @|va_list|, |
| 359 | constructed on the assumption that @<kwfirst> is the enclosing function's |
| 360 | final keyword argument; a null pointer; and the value zero (signifying an |
| 361 | empty keyword-argument vector). |
| 362 | |
| 363 | If the variable @<kw> was declared using \descref{KWDECL}{mac} and the |
| 364 | function @|@<set>{}_kwparse| has been defined using |
| 365 | \descref{KWSET_PARSEFN}{mac} then the effect is to parse the keyword |
| 366 | arguments passed to the function and set the members of @<kw> |
| 367 | appropriately. |
| 368 | \end{describe} |
| 369 | |
| 370 | \begin{describe}[KWPARSE]{mac}{KWPARSE(@<set>);} |
| 371 | The macro @|KWPARSE| (note the lack of underscore) combines |
| 372 | \descref{KWDECL}{mac} and \descref{KW_PARSE}{mac}. It declares and |
| 373 | initializes a keyword argument structure variable with the fixed name |
| 374 | @|kw|, and parses the keyword arguments provided to the enclosing function, |
| 375 | storing the results in @|kw|. It assumes that the first keyword name is in |
| 376 | an argument named @|kwfirst_|, as set up by the |
| 377 | \descref{KWTAIL}[marker]{mac}. |
| 378 | |
| 379 | The macro expands both to a variable declaration and a statement: in C89, |
| 380 | declarations must precede statements, so under C89 rules this macro must |
| 381 | appear exactly between the declarations at the head of a brace-enclosed |
| 382 | block (typically the function body) and the statements at the end. This |
| 383 | restriction was lifted in C99, so the macro may appear anywhere in the |
| 384 | function body. However, it is recommended that callers avoid taking |
| 385 | actions which might require cleanup before attempting to parse their |
| 386 | keyword arguments, since keyword argument parsing functions invoke the |
| 387 | @|kw_unknown| handler (\xref{sec:runtime.keywords.unknown}) if they |
| 388 | encounter an unknown keyword, and the calling function will not get a |
| 389 | chance to tidy up after itself if this happens. |
| 390 | \end{describe} |
| 391 | |
| 392 | As mentioned above, it is not permitted to define an empty keyword set. |
| 393 | (Specifically, invoking \descref{KWSET_STRUCT}{mac} for an empty keyword set |
| 394 | would result in attempting to define a structure with no members, which C |
| 395 | doesn't allow.) On the other hand, keyword arguments are a useful extension |
| 396 | mechanism, and it's useful to be able to define a function which doesn't |
| 397 | currently accept any keywords, but which might in the future be extended to |
| 398 | allow keyword arguments. |
| 399 | |
| 400 | \begin{describe}[KW_PARSE_EMPTY]{mac}{KW_PARSE_EMPTY(@<set>, @<kwfirst>);} |
| 401 | This is an analogue to \descref{KW_PARSE}{mac} which checks the keyword |
| 402 | argument list for a function which accepts no keyword arguments. |
| 403 | |
| 404 | It calls the \descref{kw_parseempty}[function]{fun} with five arguments: |
| 405 | the @<set> name, as a string; the string pointer @<kwfirst>; the address of |
| 406 | a temporary argument-tail cursor object of type @|va_list|, constructed on |
| 407 | the assumption that @<kwfirst> is the enclosing function's final keyword |
| 408 | argument; a null pointer; and the value zero (signifying an empty |
| 409 | keyword-argument vector). |
| 410 | |
| 411 | The effect is to check that the argument tail contains no keyword arguments |
| 412 | other than the special predefined ones. |
| 413 | \end{describe} |
| 414 | |
| 415 | \begin{describe}[KWPARSE_EMPTY]{mac}{KWPARSE_EMPTY(@<set>);} |
| 416 | This is an analogue to \descref{KWPARSE}{mac} which checks that the |
| 417 | enclosing function has been passed no keyword arguments other than the |
| 418 | special predefined ones. It assumes that the first keyword name is in an |
| 419 | argument named @|kwfirst_|, as set up by the \descref{KWTAIL}[marker]{mac}. |
| 420 | \end{describe} |
| 421 | |
| 422 | \begin{describe}[kw_parseempty]{fun} |
| 423 | {void kw_parseempty(\=const char *@<set>, |
| 424 | const char *@<kwfirst>, va_list *@<ap>, \+ \\ |
| 425 | const struct kwval *@<v>, size_t @<n>);} |
| 426 | This function checks an keyword argument list to make sure that contains no |
| 427 | keyword arguments (other than the special ones described in |
| 428 | \xref{sec:runtime.keywords.calling}). |
| 429 | |
| 430 | The @<set> argument should point to a null-terminated string: this will be |
| 431 | reported as the keyword set name to \descref{kw_unknown}{fun}, though it |
| 432 | need not (and likely will not) refer to any defined keyword set. The |
| 433 | remaining arguments are as for the keyword parsing functions defined by the |
| 434 | \descref{KWSET_PARSEFN}[macro]{mac}. |
| 435 | \end{describe} |
| 436 | |
| 437 | \subsection{Function wrappers} \label{sec:runtime.keywords.wrappers} |
| 438 | |
| 439 | Most users will not need the hairy machinery involving argument vectors. |
| 440 | Their main use is in defining \emph{wrapper functions}. Suppose there is a |
| 441 | function @<f> which accepts some keyword arguments, and we want to write a |
| 442 | function @<g> which accepts the same keywords recognized by @<f> and some |
| 443 | additional ones. Unfortunately @<f> may behave differently depending on |
| 444 | whether or not a particular keyword argument is supplied at all, but it's not |
| 445 | possible to synthesize a valid @|va_list| other than by simply capturing a |
| 446 | live argument tail, and it's not possible to decide at runtime whether or not |
| 447 | to include some arguments in a function call. It's still possible to write |
| 448 | @<g>, by building a vector of keyword arguments, collected one-by-one |
| 449 | depending on the corresponding @`_suppliedp' flags. |
| 450 | |
| 451 | A few macros are provided to make this task easier. |
| 452 | |
| 453 | \begin{describe}[KW_COUNT]{mac}{KW_COUNT(@<set>)} |
| 454 | Returns the number of keywords defined in a keyword set named @<set>. |
| 455 | \end{describe} |
| 456 | |
| 457 | \begin{describe}[KW_COPY]{mac} |
| 458 | {KW_COPY(@<fromset>, @<toset>, @<kw>, @<v>, @<n>);} |
| 459 | |
| 460 | The macro @|KW_COPY| populates a vector of @|kwval| structures from a |
| 461 | keyword-argument structure. |
| 462 | |
| 463 | The @<fromset> and @<toset> arguments should be the names of keyword sets; |
| 464 | @<kw> should be an lvalue of type @|@<fromset>{}_kwargs|; @<v> should be |
| 465 | the base address of a sufficiently large vector of @|struct kwval| objects; |
| 466 | and @<n> should be an lvalue of some appropriate integer type. The |
| 467 | @<toset> must be a subset of @<fromset>: i.e., for every keyword defined in |
| 468 | @<toset> there is a keyword defined in @<fromset> with the same name and |
| 469 | type. |
| 470 | |
| 471 | Successive elements of @<v>, starting at index @<n>, are filled in to refer |
| 472 | to the keyword arguments defined in @<toset> whose @`_suppliedp' flag is |
| 473 | set in the argument structure pointed to by @<kw>; for each such argument, |
| 474 | a pointer to the keyword name is stored in the corresponding vector |
| 475 | element's @|kw| member, and a pointer to the argument value, held in the |
| 476 | keyword argument structure, is stored in the vector element's @|val| |
| 477 | member. |
| 478 | |
| 479 | At the end of this, the index @<n> is advanced so as to contain the index |
| 480 | of the first unused element of @<v>. Hence, at most @|KW_COUNT(@<toset>)| |
| 481 | elements of @<v> will be used. |
| 482 | \end{describe} |
| 483 | |
| 484 | |
| 485 | \subsection{Handling unknown-keyword errors} |
| 486 | \label{sec:runtime.keywords.unknown} |
| 487 | |
| 488 | When parsing a variable-length argument tail, it is not possible to continue |
| 489 | after encountering an unknown keyword name. This is because it is necessary |
| 490 | to know the (promoted) type of the following argument value in order to skip |
| 491 | past it; but the only clue provided as to the type is the keyword name, which |
| 492 | in this case is meaningless. |
| 493 | |
| 494 | In this situation, the parser functions generated by |
| 495 | \descref{KWSET_PARSEFN}{mac} (and the \descref{kw_parseempty}[function]{fun}) |
| 496 | call @|kw_unknown|. |
| 497 | |
| 498 | \begin{describe}[kw_unknown]{fun} |
| 499 | {void kw_unknown(const char *@<set>, const char *@<kw>);} |
| 500 | |
| 501 | This is a function of two arguments: @<set> points to the name of the |
| 502 | keyword set expected by the caller, as a null-terminated string; and @<kw> |
| 503 | is the unknown keyword which was encountered. All that @|kw_unknown| does |
| 504 | is invoke the function whose address is stored in the global variable |
| 505 | \descref{kw_unkhook}{var} with the same arguments. |
| 506 | |
| 507 | This function never returns to its caller: if the @|kw_unkhook| function |
| 508 | returns (which it shouldn't) then @|kw_unknown| writes a fatal error |
| 509 | message to the standard error stream and calls \man{abort}{3}. |
| 510 | \end{describe} |
| 511 | |
| 512 | \begin{describe}[kw_unkhookfn]{type} |
| 513 | {typedef void kw_unkhookfn(const char *@<set>, const char *@<kw>);} |
| 514 | |
| 515 | The @|kw_unkhookfn| type is the type of unknown-keyword handler functions. |
| 516 | A handler function is given two arguments, both of which are pointers to |
| 517 | null-terminated strings: @<set> is the name of the keyword set expected; |
| 518 | and @<kw> is the name of the offending unknown keyword. |
| 519 | \end{describe} |
| 520 | |
| 521 | \begin{describe}[kw_unkhook]{var}{kw_unkhookfn *kw_unkhook} |
| 522 | This variable\footnote{% |
| 523 | Having a single global hook variable is obviously inadequate for a modern |
| 524 | library, but dealing with multiple threads isn't currently possible |
| 525 | without writing (moderately complex) system-specific code which would be |
| 526 | out of place in this library. The author's intention is that the hook |
| 527 | variable @|kw_unkhook| be `owned' by some external library which can make |
| 528 | its functionality available to client programs in a safer and more |
| 529 | convenient way. On Unix-like platforms (including Cygwin) that library |
| 530 | will be (a later version of) \textbf{mLib}; other platforms will likely |
| 531 | need different arrangements. The author is willing to coordinate any |
| 532 | such efforts.} % |
| 533 | holds the current unknown-keyword handler function. It will be invoked by |
| 534 | \descref{kw_unknown}{fun}. The function may take whatever action seems |
| 535 | appropriate, but should not return to its caller. |
| 536 | |
| 537 | Initially, this variable points to the |
| 538 | \descref{kw_defunknown}[function]{fun}. |
| 539 | \end{describe} |
| 540 | |
| 541 | \begin{describe}[kw_defunknown]{fun} |
| 542 | {void kw_defunknown(const char *@<set>, const char *@<kw>);} |
| 543 | This function simply writes a message to standard error, to the effect that |
| 544 | the keyword named by @<kw> is not known in the keyword set @<set>, and |
| 545 | calls \man{abort}{3}. |
| 546 | |
| 547 | This function is the default value of the \descref{kw_unkhook}[hook |
| 548 | variable]{var}. |
| 549 | \end{describe} |
| 550 | |
| 551 | As an example of the kind of special effect which can be achieved using this |
| 552 | hook, the following hacking answers whether a function recognizes a |
| 553 | particular keyword argument. |
| 554 | |
| 555 | \begin{prog} |
| 556 | \#define KWARGS_TEST(k, val) KWARGS(K(k, val) K(kw.unknown, 0)) |
| 557 | \\+ |
| 558 | static jmp_buf kw_test_jmp; |
| 559 | \\+ |
| 560 | static void kw_test_unknown(const char *set, const char *kw) \\ |
| 561 | \{ \\ \ind |
| 562 | if (strcmp(kw, "kw.unknown")) longjmp(kw_test_jmp, 1); \\ |
| 563 | else longjmp(kw_test_jmp, 2); \- \\ |
| 564 | \} |
| 565 | \\+ |
| 566 | \#define KW_TEST(flag, set, call) do \{ @\\ \\ \ind |
| 567 | kw_unkhookfn *oldunk = kw_unkhook; @\\ \\ |
| 568 | kw_unkhook = kw_test_unknown; @\\ \\ |
| 569 | switch (setjmp(kw_test_jmp)) \{ @\\ \\ \ind |
| 570 | case 0: call; abort(); @\\ \\ |
| 571 | case 1: flag = 1; break; @\\ \\ |
| 572 | case 2: flag = 0; break; @\\ \\ |
| 573 | default: abort(); \- @\\ \\ |
| 574 | \} @\\ \\ |
| 575 | kw_unkhook = oldunk; \- @\\ \\ |
| 576 | \} while (0) |
| 577 | \\+ |
| 578 | /* Example of use */ \\ |
| 579 | int f; \\ |
| 580 | KW_TEST(f, somefunc(1, "two", 3, KWARGS_TEST("shiny", 68.7))); \\ |
| 581 | /\=* now f is nonzero if `somefunc' accepts the `shiny' keyword \+ \\ |
| 582 | {}* (which we hope wants a double argument) \\ |
| 583 | {}*/ |
| 584 | \end{prog} |
| 585 | |
| 586 | %%%-------------------------------------------------------------------------- |
| 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. |
| 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 | |
| 598 | |
| 599 | \subsection{Infrastructure macros} \label{ch:runtime.object.infra} |
| 600 | |
| 601 | The runtime support functionality defined here generally expects that |
| 602 | instances and classes inherit from the standard @|SodObject| root object. |
| 603 | While the translator can (at some effort) support alternative roots, they |
| 604 | will require different run-time support machinery. |
| 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 | |
| 611 | \begin{describe}[SOD_XCHAIN]{mac} |
| 612 | {void *SOD_CHAIN(@<chead>, const @<cls> *@<obj>);} |
| 613 | Performs a `cross-chain upcast'. |
| 614 | |
| 615 | Given a pointer @<obj> to an instance of a class of type @<cls> and the |
| 616 | nickname @<chead> of the least specific class in one of @<cls>'s superclass |
| 617 | chains which does not contain @<cls> itself, @|SOD_XCHAIN| returns the |
| 618 | address of that chain's storage within the instance layout as a raw |
| 619 | @|void~*| pointer. (Note that @<cls> is not mentioned explicitly.) |
| 620 | |
| 621 | This macro is used by the generated @|@<CLASS>{}__CONV_@<CLS>| conversion |
| 622 | macros, which you are encouraged to use instead where possible. |
| 623 | \end{describe} |
| 624 | |
| 625 | \begin{describe}[SOD_OFFSETDIFF]{mac} |
| 626 | {ptrdiff_t SOD_OFFSETDIFF(@<type>, @<member>_1, @<member>_2);} |
| 627 | Returns the signed offset between two members of a structure or union type. |
| 628 | |
| 629 | Given a structure or union type @<type>, and two member names @<member>_1 |
| 630 | and @<member>_2, then @|SOD_OFFSETDIFF| gives the difference, in bytes, |
| 631 | between the addresses of objects @|$x$.@<member>_1| and @|$x$.@<member>_2| |
| 632 | for any object $x$ of type @<type>. |
| 633 | |
| 634 | This macro is used internally when generating vtables and is not expected |
| 635 | to be very useful elsewhere. |
| 636 | \end{describe} |
| 637 | |
| 638 | \begin{describe}[SOD_ILAYOUT]{mac} |
| 639 | {@<cls>{}__ilayout *SOD_ILAYOUT(@<cls>, @<chead>, const void *@<obj>);} |
| 640 | Recovers the instance layout base address from a pointer to one of its |
| 641 | instance chains. |
| 642 | |
| 643 | Specifically, given a class name @<cls>, the nickname @<chead> of the least |
| 644 | specific class in one of @<cls>'s superclass chains, and a pointer @<obj> |
| 645 | to the instance storage for the chain containing @<chead> within a direct |
| 646 | instance of @<cls> (i.e., not an instance of any proper subclass), |
| 647 | @|SOD_ILAYOUT| returns the a pointer to the layout structure containing |
| 648 | @<obj>. |
| 649 | |
| 650 | This macro is used internally in effective method bodies and is not |
| 651 | expected to be very useful elsewhere since it's unusual to have such |
| 652 | specific knowledge about the dynamic type of an instance. The |
| 653 | @|SOD_INSTBASE| macro (described below) is more suited to general use. |
| 654 | \end{describe} |
| 655 | |
| 656 | |
| 657 | \subsection{Utility macros} \label{sec:runtime.object.utility} |
| 658 | |
| 659 | The following macros are expected to be useful in Sod method definitions and |
| 660 | client code. |
| 661 | |
| 662 | \begin{describe}[SOD_CLASSOF]{mac} |
| 663 | {const void *SOD_CLASSOF(const @<cls> *@<obj>);} |
| 664 | Returns the class object describing an instance's dynamic class. |
| 665 | |
| 666 | Given a pointer @<obj> to an instance, @|SOD_CLASSOF| returns a pointer to |
| 667 | @<obj>'s dynamic class, which (assuming @<obj> is typed correctly in the |
| 668 | first place) will be a subclass of @<cls>. (If you wanted the class object |
| 669 | for @<cls> itself, it's called @|@<cls>{}__class|.) |
| 670 | \end{describe} |
| 671 | |
| 672 | \begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @<cls> *@<obj>)} |
| 673 | Finds the base address of an instance's layout. |
| 674 | |
| 675 | Given a pointer @<obj> to an instance, @|SOD_INSTBASE| returns the base |
| 676 | address of the storage allocated to @<obj>. This is useful if you want to |
| 677 | free a dynamically allocated instance, for example. |
| 678 | |
| 679 | This macro needs to look up an offset in @<obj>'s vtable to do its work. |
| 680 | Compare @|SOD_ILAYOUT| above, which is faster but requires precise |
| 681 | knowledge of the instance's dynamic class. |
| 682 | \end{describe} |
| 683 | |
| 684 | \begin{describe}[SOD_CONVERT]{mac} |
| 685 | {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);} |
| 686 | |
| 687 | Perform general conversions (up-, down-, and cross-casts) on instance |
| 688 | pointers. |
| 689 | |
| 690 | Given a class name @<cls> and a pointer @<obj> to an instance, |
| 691 | @|SOD_CONVERT| returns an appropriately converted pointer to @<obj> if |
| 692 | @<obj> is indeed an instance of (some subclass of) @<cls>; otherwise it |
| 693 | returns a null pointer. |
| 694 | |
| 695 | This macro is a simple wrapper around the @|sod_convert| function described |
| 696 | below, which is useful in the common case that the target class is known |
| 697 | statically. |
| 698 | \end{describe} |
| 699 | |
| 700 | \begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>);} |
| 701 | Declares and initializes an instance with automatic storage duration. |
| 702 | |
| 703 | Given a class name @<cls> and an identifier @<var>, @|SOD_DECL| declares |
| 704 | @<var> to be a pointer to an instance of @<cls>. The instance is |
| 705 | initialized in the sense that its vtable and class pointers have been set |
| 706 | up, and slots for which initializers are defined are set to the appropriate |
| 707 | initial values. |
| 708 | |
| 709 | The instance has automatic storage duration: pointers to it will become |
| 710 | invalid when control exits the scope of the declaration. |
| 711 | \end{describe} |
| 712 | |
| 713 | |
| 714 | \subsection{Functions} \label{sec:runtime.object.functions} |
| 715 | |
| 716 | The following functions are provided in @|libsod|. |
| 717 | |
| 718 | \begin{describe}[sod_subclassp]{fun} |
| 719 | {int sod_subclassp(const SodClass *@<sub>, const SodClass *@<super>);} |
| 720 | |
| 721 | Decide whether one class @<sub> is actually a subclass of another class |
| 722 | @<super>. |
| 723 | |
| 724 | The @<sod_subclassp> function returns nonzero if and only if |
| 725 | @<sub> is a subclass of @<super>. |
| 726 | |
| 727 | This involves a run-time trawl through the class structures: while some |
| 728 | effort has been made to make it perform well it's still not very fast. |
| 729 | \end{describe} |
| 730 | |
| 731 | \begin{describe}[sod_convert]{fun} |
| 732 | {void *sod_convert(const SodClass *@<cls>, const void *@<obj>);} |
| 733 | Performs general conversions (up-, down-, and cross-casts) on instance |
| 734 | pointers. |
| 735 | |
| 736 | Given a class pointer @<cls> and an instance pointer @<obj>, @|sod_convert| |
| 737 | returns an appropriately converted pointer to @<obj> in the case that |
| 738 | @<obj> is an instance of (some subclass of) @<cls>; otherwise it returns |
| 739 | null. |
| 740 | |
| 741 | This involves a run-time trawl through the class structures: while some |
| 742 | effort has been made to make it perform well it's still not very fast. For |
| 743 | upcasts (where @<cls> is a superclass of the static type of @<obj>) the |
| 744 | automatically defined conversion macros should be used instead, because |
| 745 | they're much faster and can't fail. When the target class is known |
| 746 | statically, it's slightly more convenient to use the @|SOD_CONVERT| macro |
| 747 | instead. |
| 748 | \end{describe} |
| 749 | |
| 750 | %%%----- That's all, folks -------------------------------------------------- |
| 751 | |
| 752 | %%% Local variables: |
| 753 | %%% mode: LaTeX |
| 754 | %%% TeX-master: "sod.tex" |
| 755 | %%% TeX-PDF-mode: t |
| 756 | %%% End: |