X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/f64eb323a5798e155cc494043f5f750abf50a482..d9db9c73add5814057a80e9969c74419ce30e664:/doc/runtime.tex diff --git a/doc/runtime.tex b/doc/runtime.tex index 7afe8bf..7ca8cbd 100644 --- a/doc/runtime.tex +++ b/doc/runtime.tex @@ -34,7 +34,8 @@ described in \xref{ch:structures}. This section describes the types, macros, and functions exposed in the @|| header file which provides support for defining and -calling functions which make use of keyword arguments; see \xref{sec:concepts.keywords}. +calling functions which make use of keyword arguments; see +\xref{sec:concepts.keywords}. \subsection{Type definitions} \label{sec:sec:runtime.keywords.types} @@ -42,10 +43,10 @@ calling functions which make use of keyword arguments; see \xref{sec:concepts.ke The header file defines two simple structure types, and a function type which will be described later. -\begin{describe}[struct kwval]{type} - {struct kwval \{ \\ \ind - const char *kw; \\ - const void *val; \- \\ +\begin{describe}{type}[struct kwval] + {struct kwval \{ \\ \ind + const char *kw; \\ + const void *val; \-\\ \};} The @|kwval| structure describes a keyword argument name/value pair. The @@ -55,10 +56,10 @@ will be described later. the actual argument type.) \end{describe} -\begin{describe}[struct kwtab]{type} - {struct kwtab \{ \\ \ind - const struct kwval *v; \\ - size_t n; \- \\ +\begin{describe}{type}[struct kwtab] + {struct kwtab \{ \\ \ind + const struct kwval *v; \\ + size_t n; \-\\ \};} The @|kwtab| structure describes a list of keyword arguments, represented @@ -136,7 +137,7 @@ result will be unbounded recursion or some other bad outcome. The following macros are intended to help with constructing keyword argument lists. Their use is not essential, but may help prevent errors. -\begin{describe}[KWARGS]{mac}{KWARGS(@)} +\begin{describe}{mac}[KWARGS]{KWARGS(@)} The @ encloses a sequence of keyword arguments expressed as calls to argument consists of a sequence of calls to the keyword-argument macros described below, one after another without any separation. @@ -158,18 +159,18 @@ lists. Their use is not essential, but may help prevent errors. The following keyword-argument macros can be used within the @|KWARGS| @ argument. -\begin{describe}[K]{mac}{K(@, @)} +\begin{describe}{mac}[K]{K(@, @)} Passes a keyword @ and its corresponding @, as a pair of arguments. The @ should be a single identifier (not a quoted string). The @ may be any C expression of the appropriate type. \end{describe} -\begin{describe}[K_VALIST]{mac}{K_VALIST(@)} +\begin{describe}{mac}[K_VALIST]{K_VALIST(@)} Passes an indirect variable-length argument tail. The argument @ should be an lvalue of type @|va_list|, which will be passed by reference. \end{describe} -\begin{describe}[K_TAB]{mac}{K_TAB(@, @)} +\begin{describe}{mac}[K_TAB]{K_TAB(@, @)} Passes a vector of keyword arguments. The argument @ should be the base address of the vector, and @ should be the number of elements in the vector. @@ -203,8 +204,8 @@ list items of the form \end{prog} with no separation between them. For example: \begin{prog} - \#define example_KWSET(_) @\\ \\ \ind - _(int, x, 0) @\\ \\ + \#define example_KWSET(_) \macsl \\ \ind + _(int, x, 0) \macsl \\ _(const char *, y, NULL) \end{prog} @@ -261,7 +262,7 @@ definitions of functions which accept keyword arguments. The following macros define data types and functions used for collecting keyword arguments. -\begin{describe}[KWSET_STRUCT]{mac}{KWSET_STRUCT(@);} +\begin{describe}{mac}[KWSET_STRUCT]{KWSET_STRUCT(@);} The @|KWSET_STRUCT| macro defines a \emph{keyword structure} named @|struct @{}_kwargs|. For each argument defined in the keyword set, this structure contains two members: one has exactly the @ and @ @@ -269,7 +270,7 @@ keyword arguments. type @|unsigned int| named @|@{}_suppliedp|. \end{describe} -\begin{describe}[KWDECL]{mac} +\begin{describe}{mac}[KWDECL] {@ KWDECL(@, @);} The macro declares and initializes a keyword argument structure variable named @ for the named keyword @. The optional @@ -279,15 +280,16 @@ keyword arguments. corresponding defaults from the keyword-set definition. \end{describe} -\begin{describe}[KWSET_PARSEFN]{mac} +\begin{describe}{mac}[KWSET_PARSEFN] {@ KWSET_PARSEFN(@)} The macro @|KWSET_PARSEFN| defines a keyword argument \emph{parser function} \begin{prog} - void @{}_kwparse(\=struct @{}_kwargs *@, - const char *@, va_list *@, \+ \\ - const struct kwval *@, size_t @); + void @{}_kwparse% + (\=struct @{}_kwargs *@, + const char *@, va_list *@, \+\\ + const struct kwval *@, size_t @); \end{prog} The macro call can (and usually will) be preceded by storage class specifiers such as @|static|, for example to adjust the linkage of the @@ -311,7 +313,7 @@ keyword arguments. purpose, the argument vector @ is scanned \emph{after} the variable-length argument tail captured in @.) - The variable-argument tail is read from the list described by @|* @|. + The variable-argument tail is read from the list described by @|*@|. The argument tail is expected to consist of alternating keyword strings (as ordinary null-terminated strings) and the corresponding values, terminated by a null pointer of type @|const char~*| in place of a keyword; except @@ -327,7 +329,7 @@ keyword arguments. which expects keyword arguments, but don't supply any and forget the null pointer which terminates the (empty) list.} % If @ is a null pointer, then @ need not be a valid pointer; - otherwise, the cursor object @|* @| will be modified as the function + otherwise, the cursor object @|*@| will be modified as the function extracts successive arguments from the tail. The keyword vector is read from the vector of @|kwval| structures starting @@ -343,7 +345,7 @@ keyword arguments. The following macros make use of the definitions described above to actually make a function's keyword arguments available to it. -\begin{describe}[KW_PARSE]{mac}{KW_PARSE(@, @, @);} +\begin{describe}{mac}[KW_PARSE]{KW_PARSE(@, @, @);} The @|KW_PARSE| macro invokes a keyword argument parsing function. The @ argument should name a keyword set; @ should be an lvalue of type @|struct @{}_kwargs|; and @ should be the name of the @@ -364,7 +366,7 @@ make a function's keyword arguments available to it. appropriately. \end{describe} -\begin{describe}[KWPARSE]{mac}{KWPARSE(@);} +\begin{describe}{mac}[KWPARSE]{KWPARSE(@);} The macro @|KWPARSE| (note the lack of underscore) combines \descref{KWDECL}{mac} and \descref{KW_PARSE}{mac}. It declares and initializes a keyword argument structure variable with the fixed name @@ -394,7 +396,7 @@ mechanism, and it's useful to be able to define a function which doesn't currently accept any keywords, but which might in the future be extended to allow keyword arguments. -\begin{describe}[KW_PARSE_EMPTY]{mac}{KW_PARSE_EMPTY(@, @);} +\begin{describe}{mac}[KW_PARSE_EMPTY]{KW_PARSE_EMPTY(@, @);} This is an analogue to \descref{KW_PARSE}{mac} which checks the keyword argument list for a function which accepts no keyword arguments. @@ -409,17 +411,18 @@ allow keyword arguments. other than the special predefined ones. \end{describe} -\begin{describe}[KWPARSE_EMPTY]{mac}{KWPARSE_EMPTY(@);} +\begin{describe}{mac}[KWPARSE_EMPTY]{KWPARSE_EMPTY(@);} This is an analogue to \descref{KWPARSE}{mac} which checks that the enclosing function has been passed no keyword arguments other than the special predefined ones. It assumes that the first keyword name is in an argument named @|kwfirst_|, as set up by the \descref{KWTAIL}[marker]{mac}. \end{describe} -\begin{describe}[kw_parseempty]{fun} - {void kw_parseempty(\=const char *@, - const char *@, va_list *@, \+ \\ - const struct kwval *@, size_t @);} +\begin{describe}{fun}[kw_parseempty] + {void kw_parseempty% + (\=const char *@, + const char *@, va_list *@, \+\\ + const struct kwval *@, size_t @);} This function checks an keyword argument list to make sure that contains no keyword arguments (other than the special ones described in \xref{sec:runtime.keywords.calling}). @@ -447,11 +450,11 @@ depending on the corresponding @`_suppliedp' flags. A few macros are provided to make this task easier. -\begin{describe}[KW_COUNT]{mac}{KW_COUNT(@)} +\begin{describe}{mac}[KW_COUNT]{KW_COUNT(@)} Returns the number of keywords defined in a keyword set named @. \end{describe} -\begin{describe}[KW_COPY]{mac} +\begin{describe}{mac}[KW_COPY] {KW_COPY(@, @, @, @, @);} The macro @|KW_COPY| populates a vector of @|kwval| structures from a @@ -492,7 +495,7 @@ In this situation, the parser functions generated by \descref{KWSET_PARSEFN}{mac} (and the \descref{kw_parseempty}[function]{fun}) call @|kw_unknown|. -\begin{describe}[kw_unknown]{fun} +\begin{describe}{fun}[kw_unknown] {void kw_unknown(const char *@, const char *@);} This is a function of two arguments: @ points to the name of the @@ -506,7 +509,7 @@ call @|kw_unknown|. message to the standard error stream and calls \man{abort}{3}. \end{describe} -\begin{describe}[kw_unkhookfn]{type} +\begin{describe}{type}[kw_unkhookfn] {typedef void kw_unkhookfn(const char *@, const char *@);} The @|kw_unkhookfn| type is the type of unknown-keyword handler functions. @@ -515,7 +518,7 @@ call @|kw_unknown|. and @ is the name of the offending unknown keyword. \end{describe} -\begin{describe}[kw_unkhook]{var}{kw_unkhookfn *kw_unkhook} +\begin{describe}{var}[kw_unkhook]{kw_unkhookfn *kw_unkhook} This variable\footnote{% Having a single global hook variable is obviously inadequate for a modern library, but dealing with multiple threads isn't currently possible @@ -535,7 +538,7 @@ call @|kw_unknown|. \descref{kw_defunknown}[function]{fun}. \end{describe} -\begin{describe}[kw_defunknown]{fun} +\begin{describe}{fun}[kw_defunknown] {void kw_defunknown(const char *@, const char *@);} This function simply writes a message to standard error, to the effect that the keyword named by @ is not known in the keyword set @, and @@ -551,32 +554,33 @@ particular keyword argument. \begin{prog} \#define KWARGS_TEST(k, val) KWARGS(K(k, val) K(kw.unknown, 0)) - \\+ + \\+ static jmp_buf kw_test_jmp; - \\+ - static void kw_test_unknown(const char *set, const char *kw) \\ - \{ \\ \ind - if (strcmp(kw, "kw.unknown")) longjmp(kw_test_jmp, 1); \\ - else longjmp(kw_test_jmp, 2); \- \\ - \} - \\+ - \#define KW_TEST(flag, set, call) do \{ @\\ \\ \ind - kw_unkhookfn *oldunk = kw_unkhook; @\\ \\ - kw_unkhook = kw_test_unknown; @\\ \\ - switch (setjmp(kw_test_jmp)) \{ @\\ \\ \ind - case 0: call; abort(); @\\ \\ - case 1: flag = 1; break; @\\ \\ - case 2: flag = 0; break; @\\ \\ - default: abort(); \- @\\ \\ - \} @\\ \\ - kw_unkhook = oldunk; \- @\\ \\ - \} while (0) - \\+ - /* Example of use */ \\ - int f; \\ + \\+ + static void kw_test_unknown(const char *set, const char *kw) \\ + \{ \\ \ind + if (strcmp(kw, "kw.unknown")) longjmp(kw_test_jmp, 1); \\ + else longjmp(kw_test_jmp, 2); \-\\ + \} \\+ + + \#define KW_TEST(flag, set, call) do \{ \macsl \\ \ind + kw_unkhookfn *oldunk = kw_unkhook; \macsl \\ + kw_unkhook = kw_test_unknown; \macsl \\ + switch (setjmp(kw_test_jmp)) \{ \macsl \\ \ind + case 0: call; abort(); \macsl \\ + case 1: flag = 1; break; \macsl \\ + case 2: flag = 0; break; \macsl \\ + default: abort(); \macsl\-\\ + \} \macsl \\ + kw_unkhook = oldunk; \macsl\-\\ + \} while (0) \\+ + + @/* Example of use */ \\ + int f; \\ KW_TEST(f, somefunc(1, "two", 3, KWARGS_TEST("shiny", 68.7))); \\ - /\=* now f is nonzero if `somefunc' accepts the `shiny' keyword \+ \\ - {}* (which we hope wants a double argument) \\ + /\=* \comment{now @|f| is nonzero if @|somefunc| accepts the + @|shiny| keyword} \+\\ + {}* \comment{(which we hope wants a @|double| argument)} \\ {}*/ \end{prog} @@ -605,7 +609,7 @@ translator. Others may find them useful for special effects, but they can be tricky to understand and use correctly and can't really be recommended for general use. -\begin{describe}[SOD_OFFSETDIFF]{mac} +\begin{describe}{mac}[SOD_OFFSETDIFF] {ptrdiff_t SOD_OFFSETDIFF(@, @_1, @_2);} Returns the signed offset between two members of a structure or union type. @@ -618,7 +622,7 @@ general use. to be very useful elsewhere. \end{describe} -\begin{describe}[SOD_ILAYOUT]{mac} +\begin{describe}{mac}[SOD_ILAYOUT] {@{}__ilayout *SOD_ILAYOUT(@, @, const void *@);} Recovers the instance layout base address from a pointer to one of its instance chains. @@ -636,7 +640,7 @@ general use. @|SOD_INSTBASE| macro (described below) is more suited to general use. \end{describe} -\begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @ *@)} +\begin{describe}{mac}[SOD_INSTBASE]{void *SOD_INSTBASE(const @ *@)} Finds the base address of an instance's layout. Given a pointer @ to an instance, @|SOD_INSTBASE| returns the base @@ -654,7 +658,7 @@ general use. The following macros and functions query the runtime relationships between instances and classes. -\begin{describe}[SOD_CLASSOF]{mac} +\begin{describe}{mac}[SOD_CLASSOF] {const SodClass *SOD_CLASSOF(const @ *@);} Returns the class object describing an instance's dynamic class. @@ -664,7 +668,7 @@ instances and classes. for @ itself, it's called @|@{}__class|.) \end{describe} -\begin{describe}[sod_subclassp]{fun} +\begin{describe}{fun}[sod_subclassp] {int sod_subclassp(const SodClass *@, const SodClass *@);} Decide whether one class @ is actually a subclass of another class @@ -684,8 +688,8 @@ The following macros and functions are used to convert instance pointers of some (static) type into instance pointers of other static types to the same instance. -\begin{describe}[SOD_XCHAIN]{mac} - {void *SOD_CHAIN(@, const @ *@);} +\begin{describe}{mac}[SOD_XCHAIN] + {void *SOD_XCHAIN(@, const @ *@);} Performs a `cross-chain upcast'. Given a pointer @ to an instance of a class of type @ and the @@ -699,9 +703,9 @@ instance. \end{describe} \begin{describe*} - {\dhead[SOD_CONVERT]{mac} + {\dhead{mac}[SOD_CONVERT] {@ *SOD_CONVERT(@, const void *@);} - \dhead[sod_convert]{fun} + \dhead{fun}[sod_convert] {void *sod_convert(const SodClass *@, const void *@);}} Perform general conversions (up-, down-, and cross-casts) on instance pointers. @@ -738,11 +742,11 @@ allocation strategies. They don't concern themselves with allocation or deallocation, and applications are free to use any suitable mechanism. \begin{describe*} - {\dhead[SOD_INIT]{mac} + {\dhead{mac}[SOD_INIT] {@ *SOD_INIT(@, void *@

, @);} - \dhead[sod_init]{fun} + \dhead{fun}[sod_init] {void *sod_init(const SodClass *@, void *@

, \dots);} - \dhead[sod_initv]{fun} + \dhead{fun}[sod_initv] {void *sod_initv(const SodClass *@, void *@

, va_list @);}} Imprints and initializes an instance of a class @ in the storage starting at address~@

. @@ -764,7 +768,7 @@ deallocation, and applications are free to use any suitable mechanism. \xref{sec:structures.layout.instance}. \end{describe*} -\begin{describe}[sod_teardown]{fun}{int sod_teardown(void *@

);} +\begin{describe}{fun}[sod_teardown]{int sod_teardown(void *@

);} Tears down an instance of a class, releasing any resources it holds. This function is a very thin wrapper around sending the @|obj.teardown| @@ -776,7 +780,7 @@ deallocation, and applications are free to use any suitable mechanism. \subsubsection{Automatic storage duration} The following macro constructs an instance with automatic storage duration. -\begin{describe}[SOD_DECL]{mac}{SOD_DECL(@, @, @);} +\begin{describe}{mac}[SOD_DECL]{SOD_DECL(@, @, @);} Declares and initializes an instance with automatic storage duration. Given a class name @ and an identifier @, @|SOD_DECL| declares @@ -801,9 +805,9 @@ standard C heap. They don't work in freestanding implementations where @|malloc| and @|free| are not available. \begin{describe*} - {\dhead[SOD_MAKE]{mac}{@ *SOD_MAKE(@, @);} - \dhead[sod_make]{fun}{void *sod_make(const SodClass *@, \dots);} - \dhead[sod_makev]{fun} + {\dhead{mac}[SOD_MAKE]{@ *SOD_MAKE(@, @);} + \dhead{fun}[sod_make]{void *sod_make(const SodClass *@, \dots);} + \dhead{fun}[sod_makev] {void *sod_makev(const SodClass *@, va_list @);}} Constructs and returns a pointer to a new instance of @. @@ -827,7 +831,7 @@ standard C heap. They don't work in freestanding implementations where probably be used where possible. \end{describe*} -\begin{describe}[sod_destroy]{fun}{int sod_destroy(void *@

);} +\begin{describe}{fun}[sod_destroy]{int sod_destroy(void *@

);} Tears down and frees an instance allocated using @|malloc|. The pointer @

should be an instance pointer, i.e., a pointer to any of