extern "C" {
#endif
+/* Here's the overall flow for a testing session.
+ *
+ * @tvec_begin@
+ * -> output @bsession@
+ * @tvec_read@
+ * -> output @bgroup@
+ * -> env @setup@
+ * one or more tests
+ * -> type @init@ (input and output)
+ * -> type @parse@ (input)
+ * -> output @btest@
+ * -> env @before@
+ * -> @tvec_skipgroup@
+ * -> output @skipgroup@
+ * -> env @run@
+ * -> @tvec_skip@
+ * -> output @skip@
+ * -> test @fn@
+ * -> @tvec_checkregs@
+ * -> type @eq@
+ * -> @tvec_fail@
+ * -> output @fail@
+ * -> @tvec_mismatch@
+ * -> output @dumpreg@
+ * -> type @dump@
+ * -> output @etest@
+ * -> env @after@
+ * finally
+ * -> output @egroup@
+ * -> env @teardown@
+ *
+ * @tvec_adhoc@
+ * @tvec_begingroup@
+ * -> output @bgroup@
+ * -> env @setup@
+ * @tvec_begintest@
+ * -> output @btest@
+ * @tvec_skip@
+ * -> output @skip@
+ * @tvec_claimeq@
+ * -> @tvec_fail@
+ * -> output @fail@
+ * -> @tvec_mismatch@
+ * -> output @dumpreg@
+ * -> type @dump@
+ * @tvec_endtest@
+ * -> output @etest@
+ * or @tvec_skipgroup@
+ * -> output @skipgroup@
+ * @tvec_endgroup@
+ * -> output @egroup@
+ *
+ * @tvec_end@
+ * -> output @esession@
+ * -> output @destroy@
+ *
+ * @tvec_benchrun@
+ * -> type @dump@ (compact style)
+ * -> output @bbench@
+ * -> subenv @run@
+ * -> test @fn@
+ * -> output @ebench@
+ * -> @tvec_benchreport@
+ *
+ * The output functions @error@ and @notice@ can be called at arbitrary
+ * times.
+ */
+
/*----- Header files ------------------------------------------------------*/
#include <stdarg.h>
# include "gprintf.h"
#endif
+#ifndef MLIB_LBUF_H
+# include "lbuf.h"
+#endif
+
#ifndef MLIB_MACROS_H
# include "macros.h"
#endif
*/
union tvec_regval {
- /* The actual register value. This is what the type handler sees.
- * Additional members can be added by setting `TVEC_REGSLOTS' before
- * including this file.
- *
- * A register value can be /initialized/, which simply means that its
- * contents represent a valid value according to its type -- the
- * register can be compared, dumped, serialized, parsed into, etc.
- * You can't do anything safely to an uninitialized register value
- * other than initialize it.
- */
+ /* The actual register value. This is what the type handler sees.
+ * Additional members can be added by setting `TVEC_REGSLOTS' before
+ * including this file.
+ *
+ * A register value can be /initialized/, which simply means that its
+ * contents represent a valid value according to its type -- the register
+ * can be compared, dumped, serialized, parsed into, etc. You can't do
+ * anything safely to an uninitialized register value other than initialize
+ * it.
+ */
long i; /* signed integer */
unsigned long u; /* unsigned integer */
void *p; /* pointer */
double f; /* floating point */
struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
- struct { char *p; size_t sz; } str; /* text string */
+ struct { char *p; size_t sz; } text; /* text string */
+ struct { /* buffer */
+ unsigned char *p; size_t sz; /* binary string */
+ size_t a, m; /* residue and modulus */
+ size_t off; /* offset into full buffer */
+ } buf;
#ifdef TVEC_REGSLOTS
TVEC_REGSLOTS
#endif
};
struct tvec_reg {
- /* A register.
- *
- * Note that all of the registers listed as being used by a
- * particular test group are initialized at all times[1] while that
- * test group is being processed. (The other register slots don't
- * even have types associated with them, so there's nothing useful we
- * could do with them.)
- *
- * The `TVRF_LIVE' flag indicates that the register was assigned a
- * value by the test vector file: it's the right thing to use to
- * check whether an optional register is actually present. Even
- * `dead' registers are still initialized, though.
- *
- * [1] This isn't quite true. Between individual tests, the
- * registers are released and reinitialized in order to reset
- * them to known values ready for the next test. But you won't
- * see them at this point.
- */
+ /* A register.
+ *
+ * Note that all of the registers listed as being used by a particular test
+ * group are initialized at all times[1] while that test group is being
+ * processed. (The other register slots don't even have types associated
+ * with them, so there's nothing useful we could do with them.)
+ *
+ * The `TVRF_LIVE' flag indicates that the register was assigned a value by
+ * the test vector file: it's the right thing to use to check whether an
+ * optional register is actually present. Even `dead' registers are still
+ * initialized, though.
+ *
+ * [1] This isn't quite true. Between individual tests, the registers are
+ * released and reinitialized in order to reset them to known values
+ * ready for the next test. But you won't see them at this point.
+ */
unsigned f; /* flags */
#define TVRF_LIVE 1u /* used in current test */
};
struct tvec_regdef {
- /* A register definition. Register definitions list the registers
- * which are used by a particular test group (see `struct tvec_test'
- * below).
- *
- * A vector of register definitions is terminated by a definition
- * whose `name' slot is null.
- */
+ /* A register definition. Register definitions list the registers which
+ * are used by a particular test group (see `struct tvec_test' below).
+ *
+ * A vector of register definitions is terminated by a definition whose
+ * `name' slot is null.
+ */
const char *name; /* register name (for input files) */
unsigned i; /* register index */
#define TVEC_GREG(vec, i, regsz) \
((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz)))
+/*----- Register types ----------------------------------------------------*/
+
+struct tvec_state; /* forward declaration */
+
+struct tvec_regty {
+ /* A register type. */
+
+ void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
+ /* Initialize the value in @*rv@. This will be called before any other
+ * function acting on the value, including @release@.
+ */
+
+ void (*release)(union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/);
+ /* Release any resources associated with the value in @*rv@. */
+
+ int (*eq)(const union tvec_regval */*rv0*/,
+ const union tvec_regval */*rv1*/,
+ const struct tvec_regdef */*rd*/);
+ /* Return nonzero if @*rv0@ and @*rv1@ are equal values. Asymmetric
+ * criteria are permitted: @tvec_checkregs@ calls @eq@ with the input
+ * register as @rv0@ and the output as @rv1@.
+ */
+
+ int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/);
+ /* Serialize the value @*rv@, writing the result to @b@. Return zero on
+ * success, or %$-1$% on error.
+ */
+
+ int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/);
+ /* Deserialize a value from @b@, storing it in @*rv@. Return zero on
+ * success, or %$-1$% on error.
+ */
+
+ int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
+ struct tvec_state */*tv*/);
+ /* Parse a value from @tv->fp@, storing it in @*rv@. Return zero on
+ * success, or %$-1$% on error, having reported one or more errors via
+ * @tvec_error@ or @tvec_syntax@. A successful return should leave the
+ * input position at the start of the next line; the caller will flush
+ * the remainder of the line itself.
+ */
+
+ void (*dump)(const union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/,
+ unsigned /*style*/,
+ const struct gprintf_ops */*gops*/, void */*go*/);
+#define TVSF_COMPACT 1u
+ /* Write a human-readable representation of the value @*rv@ using
+ * @gprintf@ on @gops@ and @go@. The @style@ is a collection of flags:
+ * if @TVSF_COMPACT@ is set, then output should be minimal, and must fit
+ * on a single line; otherwise, output may consist of multiple lines and
+ * may contain redundant information if that is likely to be useful to a
+ * human reader.
+ */
+};
+
+/*----- Test descriptions -------------------------------------------------*/
+
+typedef void tvec_testfn(const struct tvec_reg */*in*/,
+ struct tvec_reg */*out*/,
+ void */*ctx*/);
+ /* A test function. It should read inputs from @in@ and write outputs to
+ * @out@. The @TVRF_LIVE@ is set on inputs which are actually present, and
+ * on outputs which are wanted to test. A test function can set additional
+ * `gratuitous outputs' by setting @TVRF_LIVE@ on them; clearing
+ * @TVRF_LIVE@ on a wanted output causes a mismatch.
+ *
+ * A test function may be called zero or more times by the environment. In
+ * particular, it may be called multiple times, though usually by prior
+ * arrangement with the environment.
+ *
+ * The @ctx@ is supplied by the environment's @run@ function (see below).
+ * The default environment calls the test function once, with a null
+ * @ctx@. There is no expectation that the environment's context has
+ * anything to do with the test function's context.
+ */
+
+struct tvec_env;
+
+typedef int tvec_setvarfn(struct tvec_state */*tv*/, const char */*var*/,
+ const union tvec_regval */*rv*/, void */*ctx*/);
+ /* Called after a variable is read. Return zero on success or %$-1$% on
+ * error. This function is never called if the test group is skipped.
+ */
+
+struct tvec_vardef {
+ size_t regsz; /* (minimum) register size */
+ tvec_setvarfn *setvar; /* function to set variable */
+ struct tvec_regdef def; /* register definition */
+};
+
+typedef void tvec_envsetupfn(struct tvec_state */*tv*/,
+ const struct tvec_env */*env*/,
+ void */*pctx*/, void */*ctx*/);
+ /* Initialize the context; called at the start of a test group; @pctx@ is
+ * null for environments called by the core, but may be non-null for
+ * subordinate environments. If setup fails, the function should call
+ * @tvec_skipgroup@ with a suitable excuse. The @set@, @after@, and
+ * @teardown@ entry points will still be called, but @before@ and @run@
+ * will not.
+ */
+
+typedef const struct tvec_vardef *tvec_envfindvarfn
+ (struct tvec_state */*tv*/, const char */*name*/,
+ void **/*ctx_out*/, void */*ctx*/);
+ /* Called when the parser finds a %|@var|%' special variable. If a
+ * suitable variable was found, set @*ctx_out@ to a suitable context and
+ * return the variable definition; the context will be passed to the
+ * variable definition's @setvar@ function. If no suitable variable was
+ * found, then return null.
+ */
+
+typedef void tvec_envbeforefn(struct tvec_state */*tv*/, void */*ctx*/);
+ /* Called prior to running a test. This is the right place to act on any
+ * `%|@var|%' settings. If preparation fails, the function should call
+ * @tvec_skip@ with a suitable excuse. This function is never called if
+ * the test group is skipped. It %%\emph{is}%% called if the test will be
+ * skipped due to erroneous test data. It should check the @TVSF_ACTIVE@
+ * flag if necessary.
+ */
+
+typedef void tvec_envrunfn(struct tvec_state */*tv*/,
+ tvec_testfn */*fn*/, void */*ctx*/);
+ /* Run the test. It should either call @tvec_skip@, or run @fn@ one or
+ * more times. In the latter case, it is responsible for checking the
+ * outputs, and calling @tvec_fail@ as necessary; @tvec_checkregs@ will
+ * check the register values against the supplied test vector, while
+ * @tvec_check@ does pretty much everything necessary. This function is
+ * never called if the test group is skipped.
+ */
+
+typedef void tvec_envafterfn(struct tvec_state */*tv*/, void */*ctx*/);
+ /* Called after running or skipping a test. Typical actions involve
+ * resetting whatever things were established by @set@. This function
+ * %%\emph{is}%% called if the test group is skipped or the test data is
+ * erroneous, so that the test environment can reset variables set by the
+ * @set@ entry point. It should check the @TVSF_SKIP@ flag if necessary.
+ */
+
+typedef void tvec_envteardownfn(struct tvec_state */*tv*/, void */*ctx*/);
+ /* Tear down the environment: called at the end of a test group. */
+
+
+struct tvec_env {
+ /* A test environment sets things up for and arranges to run the test.
+ *
+ * The caller is responsible for allocating storage for the environment's
+ * context, based on the @ctxsz@ slot, and freeing it later; this space is
+ * passed in as the @ctx@ parameter to the remaining functions; if @ctxsz@
+ * is zero then @ctx@ is null.
+ */
+
+ size_t ctxsz; /* environment context size */
+
+ tvec_envsetupfn *setup; /* setup for group */
+ tvec_envfindvarfn *findvar; /* find variable */
+ tvec_envbeforefn *before; /* prepare for test */
+ tvec_envrunfn *run; /* run test function */
+ tvec_envafterfn *after; /* clean up after test */
+ tvec_envteardownfn *teardown; /* tear down after group */
+};
+
+struct tvec_test {
+ /* A test description. */
+
+ const char *name; /* name of the test */
+ const struct tvec_regdef *regs; /* descriptions of the registers */
+ const struct tvec_env *env; /* environment to run test in */
+ tvec_testfn *fn; /* test function */
+};
+#define TVEC_ENDTESTS { 0, 0, 0, 0 }
+
+enum {
+ /* Register output dispositions. */
+
+ TVRD_INPUT, /* input-only register */
+ TVRD_OUTPUT, /* output-only (input is dead) */
+ TVRD_MATCH, /* matching (equal) registers */
+ TVRD_FOUND, /* mismatching output register */
+ TVRD_EXPECT, /* mismatching input register */
+ TVRD_LIMIT /* (number of dispositions) */
+};
+
/*----- Test state --------------------------------------------------------*/
enum {
TVOUT_LOSE, /* test failed */
TVOUT_SKIP, /* test skipped */
TVOUT_WIN, /* test passed */
+ TVOUT_XFAIL, /* test passed, but shouldn't have */
TVOUT_LIMIT /* (number of possible outcomes) */
};
/* The primary state structure for the test vector machinery. */
unsigned f; /* flags */
-#define TVSF_SKIP 1u /* skip this test group */
-#define TVSF_OPEN 2u /* test is open */
-#define TVSF_ACTIVE 4u /* test is active */
-#define TVSF_ERROR 8u /* an error occurred */
-#define TVSF_OUTMASK 0xf0 /* test outcome (@TVOUT_...@) */
+#define TVSF_SKIP 0x0001u /* skip this test group */
+#define TVSF_OPEN 0x0002u /* test is open */
+#define TVSF_ACTIVE 0x0004u /* test is active */
+#define TVSF_ERROR 0x0008u /* an error occurred */
+#define TVSF_OUTMASK 0x00f0u /* test outcome (@TVOUT_...@) */
#define TVSF_OUTSHIFT 4 /* shift applied to outcome */
+#define TVSF_XFAIL 0x0100u /* test expected to fail */
+#define TVSF_MUFFLE 0x0200u /* muffle errors */
/* Registers. Available to execution environments. */
unsigned nrout, nreg; /* number of output/total registers */
/* Benchmarking details. */
enum {
TVBU_OP, /* counting operations of some kind */
- TVBU_BYTE /* counting bytes (@rbuf >= 0@) */
+ TVBU_BYTE, /* counting bytes (@rbuf >= 0@) */
+ TVBU_LIMIT /* (number of units) */
};
-struct bench_timing; /* forward declaration */
+struct bench_timing; /* include <mLib/bench.h> for the real definition */
struct tvec_outops {
/* Output operations. */
void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
- /* Begin a test session. The output driver will probably want to
- * save @tv@, because this isn't provided to any other methods.
- */
+ /* Begin a test session. The output driver will probably want to
+ * save @tv@, because this isn't provided to any other methods.
+ */
int (*esession)(struct tvec_output */*o*/);
- /* End a session, and return the suggested exit code. */
+ /* End a session, and return the suggested exit code. */
void (*bgroup)(struct tvec_output */*o*/);
- /* Begin a test group. The test group description is @tv->test@. */
+ /* Begin a test group. The test group description is @tv->test@. */
void (*skipgroup)(struct tvec_output */*o*/,
const char */*excuse*/, va_list */*ap*/);
- /* The group is being skipped; @excuse@ may be null or a format
- * string explaining why. The @egroup@ method will not be called
- * separately.
- */
+ /* The group is being skipped; @excuse@ may be null or a format
+ * string explaining why. The @egroup@ method will not be called
+ * separately.
+ */
void (*egroup)(struct tvec_output */*o*/);
- /* End a test group. At least one test was attempted or @skipgroup@
- * would have been called instead. If @tv->curr[TVOUT_LOSE]@ is
- * nonzero then the test group as a whole failed; otherwise it
- * passed.
- */
+ /* End a test group. At least one test was attempted or @skipgroup@
+ * would have been called instead. If @tv->curr[TVOUT_LOSE]@ is nonzero
+ * then the test group as a whole failed; otherwise it passed.
+ */
void (*btest)(struct tvec_output */*o*/);
- /* Begin a test case. */
+ /* Begin a test case. */
void (*skip)(struct tvec_output */*o*/,
const char */*excuse*/, va_list */*ap*/);
- /* The test case is being skipped; @excuse@ may be null or a format
- * string explaining why. The @etest@ function will still be called
- * (so this works differently from @skipgroup@ and @egroup@). A test
- * case can be skipped at most once, and, if skipped, it cannot fail.
- */
+ /* The test case is being skipped; @excuse@ may be null or a format
+ * string explaining why. The @etest@ function will still be called (so
+ * this works differently from @skipgroup@ and @egroup@). A test case
+ * can be skipped at most once, and, if skipped, it cannot fail.
+ */
void (*fail)(struct tvec_output */*o*/,
const char */*detail*/, va_list */*ap*/);
- /* The test case failed.
- *
- * The output driver should preferably report the filename (@infile@)
- * and line number (@test_lno@, not @lno@) for the failing test.
- *
- * The @detail@ may be null or a format string describing detail
- * about how the failing test was run which can't be determined from
- * the registers; a @detail@ is usually provided when (and only when)
- * the test environment potentially invokes the test function more
- * than once.
- *
- * A single test case can fail multiple times!
- */
+ /* The test case failed.
+ *
+ * The output driver should preferably report the filename (@infile@) and
+ * line number (@test_lno@, not @lno@) for the failing test.
+ *
+ * The @detail@ may be null or a format string describing detail about
+ * how the failing test was run which can't be determined from the
+ * registers; a @detail@ is usually provided when (and only when) the
+ * test environment potentially invokes the test function more than once.
+ *
+ * A single test case can fail multiple times!
+ */
void (*dumpreg)(struct tvec_output */*o*/,
unsigned /*disp*/, const union tvec_regval */*rv*/,
const struct tvec_regdef */*rd*/);
- /* Dump a register. The `disposition' @disp@ explains what condition
- * the register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.
- * The register value is at @rv@, and its definition, including its
- * type, at @rd@. Note that this function may be called on virtual
- * registers which aren't in either of the register vectors or
- * mentioned by the test description.
- */
+ /* Dump a register. The `disposition' @disp@ explains what condition the
+ * register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes. The
+ * register value is at @rv@, and its definition, including its type, at
+ * @rd@. Note that this function may be called on virtual registers
+ * which aren't in either of the register vectors or mentioned by the
+ * test description. It may also be called with @rv@ null, indicating
+ * that the register is not live.
+ */
void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
- /* The test case concluded with the given @outcome@ (one of the
- * @TVOUT_...@ codes.
- */
+ /* The test case concluded with the given @outcome@ (one of the
+ * @TVOUT_...@ codes.
+ */
void (*bbench)(struct tvec_output */*o*/,
const char */*ident*/, unsigned /*unit*/);
- /* Begin a benchmark. The @ident@ is a formatted string identifying
- * the benchmark based on the values of the input registered marked
- * @TVRF_ID@; the output driver is free to use this or come up with
- * its own way to identify the test, e.g., by inspecting the register
- * values for itself. The @unit@ is one of the @TVBU_...@ constants
- * explaining what sort of thing is being measured.
- */
+ /* Begin a benchmark. The @ident@ is a formatted string identifying the
+ * benchmark based on the values of the input registered marked
+ * @TVRF_ID@; the output driver is free to use this or come up with its
+ * own way to identify the test, e.g., by inspecting the register values
+ * for itself. The @unit@ is one of the @TVBU_...@ constants explaining
+ * what sort of thing is being measured.
+ */
void (*ebench)(struct tvec_output */*o*/,
const char */*ident*/, unsigned /*unit*/,
const struct bench_timing */*tm*/);
- /* End a benchmark. The @ident@ and @unit@ arguments are as for
- * @bbench@. If @tm@ is zero then the measurement failed; otherwise
- * @tm->n@ counts total number of things (operations or bytes, as
- * indicated by @unit@) processed in the indicated time.
- */
-
- void (*error)(struct tvec_output */*o*/,
- const char */*msg*/, va_list */*ap*/);
- /* Report an error. The driver should ideally report the filename
- * (@infile@) and line number (@lno@) prompting the error.
- */
-
- void (*notice)(struct tvec_output */*o*/,
- const char */*msg*/, va_list */*ap*/);
- /* Report a miscellaneous message. The driver should ideally report
- * the filename (@infile@) and line number (@lno@) prompting the
- * error.
- */
-
- void (*destroy)(struct tvec_output */*o*/);
- /* Release any resources acquired by the driver. */
-};
-
-/*----- Test descriptions -------------------------------------------------*/
-
-typedef void tvec_testfn(const struct tvec_reg */*in*/,
- struct tvec_reg */*out*/,
- void */*ctx*/);
- /* A test function. It should read inputs from @in@ and write outputs to
- * @out@. The @TVRF_LIVE@ is set on inputs which are actually present, and
- * on outputs which are wanted to test. A test function can set additional
- * `gratuitous outputs' by setting @TVRF_LIVE@ on them; clearing
- * @TVRF_LIVE@ on a wanted output causes a mismatch.
- *
- * A test function may be called zero or more times by the environment. In
- * particular, it may be called multiple times, though usually by prior
- * arrangement with the environment.
- *
- * The @ctx@ is supplied by the environment's @run@ function (see below).
- * The default environment calls the test function once, with a null
- * @ctx@. There is no expectation that the environment's context has
- * anything to do with the test function's context.
- */
-
-struct tvec_env {
- /* A test environment sets things up for and arranges to run the test.
- *
- * The caller is responsible for allocating storage for the environment's
- * context, based on the @ctxsz@ slot, and freeing it later; this space is
- * passed in as the @ctx@ parameter to the remaining functions; if @ctxsz@
- * is zero then @ctx@ is null.
- */
-
- size_t ctxsz; /* environment context size */
-
- int (*setup)(struct tvec_state */*tv*/, const struct tvec_env */*env*/,
- void */*pctx*/, void */*ctx*/);
- /* Initialize the context; called at the start of a test group; @pctx@ is
- * null for environments called by the core, but may be non-null for
- * subordinate environments. Return zero on success, or @-1@ on failure.
- * If setup fails, the context is freed, and the test group is skipped.
+ /* End a benchmark. The @ident@ and @unit@ arguments are as for
+ * @bbench@. If @tm@ is zero then the measurement failed; otherwise
+ * @tm->n@ counts total number of things (operations or bytes, as
+ * indicated by @unit@) processed in the indicated time.
*/
- int (*set)(struct tvec_state */*tv*/, const char */*var*/,
- const struct tvec_env */*env*/, void */*ctx*/);
- /* Called when the parser finds a %|@var|%' setting to parse and store
- * the value. If @setup@ failed, this is still called (so as to skip the
- * value), but @ctx@ is null.
- */
-
- int (*before)(struct tvec_state */*tv*/, void */*ctx*/);
- /* Called prior to running a test. This is the right place to act on any
- * `%|@var|%' settings. Return zero on success or @-1@ on failure (which
- * causes the test to be skipped). This function is never called if the
- * test group is skipped.
- */
-
- void (*run)(struct tvec_state */*tv*/, tvec_testfn */*fn*/, void */*ctx*/);
- /* Run the test. It should either call @tvec_skip@, or run @fn@ one or
- * more times. In the latter case, it is responsible for checking the
- * outputs, and calling @tvec_fail@ as necessary; @tvec_checkregs@ will
- * check the register values against the supplied test vector, while
- * @tvec_check@ does pretty much everything necessary. This function is
- * never called if the test group is skipped.
- */
-
- void (*after)(struct tvec_state */*tv*/, void */*ctx*/);
- /* Called after running or skipping a test. Typical actions involve
- * resetting whatever things were established by @set@. This function is
- * never called if the test group is skipped.
+ void (*report)(struct tvec_output */*o*/, unsigned /*level*/,
+ const char */*msg*/, va_list */*ap*/);
+ /* Report a message. The driver should ideally report the filename
+ * (@infile@) and line number (@lno@) prompting the error.
*/
- void (*teardown)(struct tvec_state */*tv*/, void */*ctx*/);
- /* Tear down the environment: called at the end of a test group. If the
- * setup failed, then this function is still called, with a null @ctx@.
- */
+ void (*destroy)(struct tvec_output */*o*/);
+ /* Release any resources acquired by the driver. */
};
-struct tvec_test {
- /* A test description. */
-
- const char *name; /* name of the test */
- const struct tvec_regdef *regs; /* descriptions of the registers */
- const struct tvec_env *env; /* environment to run test in */
- tvec_testfn *fn; /* test function */
-};
-#define TVEC_ENDTESTS { 0, 0, 0, 0 }
+#define TVEC_LEVELS(_) \
+ _(NOTE, "notice", 4) \
+ _(ERR, "ERROR", 8)
enum {
- /* Register output dispositions. */
-
- TVRD_INPUT, /* input-only register */
- TVRD_OUTPUT, /* output-only (input is dead) */
- TVRD_MATCH, /* matching (equal) registers */
- TVRD_FOUND, /* mismatching output register */
- TVRD_EXPECT /* mismatching input register */
-};
-
-/*----- Register types ----------------------------------------------------*/
-
-struct tvec_regty {
- /* A register type. */
-
- void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
- /* Initialize the value in @*rv@. This will be called before any
- * other function acting on the value, including @release@.
- */
-
- void (*release)(union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/);
- /* Release any resources associated with the value in @*rv@. */
-
- int (*eq)(const union tvec_regval */*rv0*/,
- const union tvec_regval */*rv1*/,
- const struct tvec_regdef */*rd*/);
- /* Return nonzero if @*rv0@ and @*rv1@ are equal values.
- * Asymmetric criteria are permitted: @tvec_checkregs@ calls @eq@
- * with the input register as @rv0@ and the output as @rv1@.
- */
-
- int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/);
- /* Serialize the value @*rv@, writing the result to @b@. Return
- * zero on success, or @-1@ on error.
- */
-
- int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/);
- /* Deserialize a value from @b@, storing it in @*rv@. Return zero on
- * success, or @-1@ on error.
- */
-
- int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
- struct tvec_state */*tv*/);
- /* Parse a value from @tv->fp@, storing it in @*rv@. Return zero on
- * success, or @-1@ on error, having reported one or more errors via
- * @tvec_error@ or @tvec_syntax@. A successful return should leave
- * the input position at the start of the next line; the caller will
- * flush the remainder of the line itself.
- */
-
- void (*dump)(const union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/,
- unsigned /*style*/,
- const struct gprintf_ops */*gops*/, void */*go*/);
-#define TVSF_COMPACT 1u
- /* Write a human-readable representation of the value @*rv@ using
- * @gprintf@ on @gops@ and @go@. The @style@ is a collection of
- * flags: if @TVSF_COMPACT@ is set, then output should be minimal,
- * and must fit on a single line; otherwise, output may consist of
- * multiple lines and may contain redundant information if that is
- * likely to be useful to a human reader.
- */
+#define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
+ TVEC_LEVELS(TVEC_DEFLEVEL)
+#undef TVEC_DEFLEVEL
+ TVLEV_LIMIT
};
/*----- Session lifecycle -------------------------------------------------*/
-/* Here's the overall flow for a testing session.
- *
- * @tvec_begin@
- * -> output @bsession@
- * @tvec_read@
- * -> output @bgroup@
- * -> env @setup@
- * one or more tests
- * -> type @init@ (input and output)
- * -> type @parse@ (input)
- * -> output @btest@
- * -> env @before@
- * -> env @run@
- * -> @tvec_skip@
- * -> output @skip@
- * -> test @fn@
- * -> @tvec_checkregs@
- * -> type @eq@
- * -> @tvec_fail@
- * -> output @fail@
- * -> @tvec_mismatch@
- * -> output @dumpreg@
- * -> type @dump@
- * -> env @after@
- * -> output @etest@
- * or
- * -> output @skipgroup@
- * finally
- * -> output @egroup@
- * -> env @teardown@
- *
- * @tvec_adhoc@
- * @tvec_begingroup@
- * -> output @bgroup@
- * -> env @setup@
- * @tvec_begintest@
- * -> output @btest@
- * @tvec_skip@
- * -> output @skip@
- * @tvec_claimeq@
- * -> @tvec_fail@
- * -> output @fail@
- * -> @tvec_mismatch@
- * -> output @dumpreg@
- * -> type @dump@
- * @tvec_endtest@
- * -> output @etest@
- * or @tvec_skipgroup@
- * -> output @skipgroup@
- * @tvec_endgroup@
- * -> output @egroup@
- *
- * @tvec_end@
- * -> output @esession@
- * -> output @destroy@
- *
- * @tvec_benchrun@
- * -> type @dump@ (compact style)
- * -> output @bbench@
- * -> subenv @run@
- * -> test @fn@
- * -> output @ebench@
- * -> @tvec_benchreport@
- *
- * The output functions @error@ and @notice@ can be called at arbitrary
- * times.
- */
-
/* --- @tvec_begin@ --- *
*
* Arguments: @struct tvec_state *tv_out@ = state structure to fill in
* @const char *infile@ = the name of the input file
* @FILE *fp@ = stream to read from
*
- * Returns: Zero on success, @-1@ on error.
+ * Returns: Zero on success, %$-1$% on error.
*
* Use: Read test vector data from @fp@ and exercise test functions.
* THe return code doesn't indicate test failures: it's only
/*----- Command-line interface --------------------------------------------*/
extern const struct tvec_config tvec_adhocconfig;
-/* A special @struct tvec_config@ to use for programs which perform ad-hoc
- * testing.
- */
+ /* A special @struct tvec_config@ to use for programs which perform ad-hoc
+ * testing.
+ */
/* --- @tvec_parseargs@ --- *
*
* @const char *file@ = pathname of file to read
* @const char *arg@ = argument to interpret
*
- * Returns: Zero on success, @-1@ on error.
+ * Returns: Zero on success, %$-1$% on error.
*
* Use: Read test vector data from stdin or a named file. The
* @tvec_readarg@ function reads from stdin if @arg@ is `%|-|%',
* Arguments: @struct tvec_state *tv@ = test vector state
* @const char *dflt@ = defsault filename or null
*
- * Returns: Zero on success, @-1@ on error.
+ * Returns: Zero on success, %$-1$% on error.
*
* Use: Reads from the default test vector data. If @file@ is null,
* then read from standard input, unless that's a terminal; if
* @int *argpos_inout@ = current argument position (updated)
* @const char *dflt@ = default filename or null
*
- * Returns: Zero on success, @-1@ on error.
+ * Returns: Zero on success, %$-1$% on error.
*
* Use: Reads from the sources indicated by the command-line
* arguments, in order, interpreting each as for @tvec_readarg@;
/*----- Test processing ---------------------------------------------------*/
-/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @const char *excuse@, @va_list *ap@ = reason why skipped
- *
- * Returns: ---
- *
- * Use: Skip the current group. This should only be called from a
- * test environment @setup@ function; a similar effect occurs if
- * the @setup@ function fails.
- */
-
-extern void PRINTF_LIKE(2, 3)
- tvec_skipgroup(struct tvec_state */*tv*/, const char */*excuse*/, ...);
-extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
- const char */*excuse*/, va_list */*ap*/);
-
-/* --- @tvec_skip@, @tvec_skip_v@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @const char *excuse@, @va_list *ap@ = reason why test skipped
- *
- * Returns: ---
- *
- * Use: Skip the current test. This should only be called from a
- * test environment @run@ function; a similar effect occurs if
- * the @before@ function fails.
- */
-
-extern void PRINTF_LIKE(2, 3)
- tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
-extern void tvec_skip_v(struct tvec_state */*tv*/,
- const char */*excuse*/, va_list */*ap*/);
-
-/* --- @tvec_resetoutputs@ --- *
+/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *excuse@, @va_list *ap@ = reason why skipped
*
* Returns: ---
*
- * Use: Reset (releases and reinitializes) the output registers in
- * the test state. This is mostly of use to test environment
- * @run@ functions, between invocations of the test function.
+ * Use: Skip the current group. This should only be called from a
+ * test environment @setup@ function; a similar effect occurs if
+ * the @setup@ function fails.
*/
-extern void tvec_resetoutputs(struct tvec_state */*tv*/);
+extern PRINTF_LIKE(2, 3)
+ void tvec_skipgroup(struct tvec_state */*tv*/,
+ const char */*excuse*/, ...);
+extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
+ const char */*excuse*/, va_list */*ap*/);
-/* --- @tvec_checkregs@ --- *
+/* --- @tvec_skip@, @tvec_skip_v@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *excuse@, @va_list *ap@ = reason why test skipped
*
- * Returns: Zero on success, @-1@ on mismatch.
- *
- * Use: Compare the active output registers (according to the current
- * test group definition) with the corresponding input register
- * values. A mismatch occurs if the two values differ
- * (according to the register type's @eq@ method), or if the
- * input is live but the output is dead.
+ * Returns: ---
*
- * This function only checks for a mismatch and returns the
- * result; it takes no other action. In particular, it doesn't
- * report a failure, or dump register values.
+ * Use: Skip the current test. This should only be called from a
+ * test environment @run@ function; a similar effect occurs if
+ * the @before@ function fails.
*/
-extern int tvec_checkregs(struct tvec_state */*tv*/);
+extern PRINTF_LIKE(2, 3)
+ void tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
+extern void tvec_skip_v(struct tvec_state */*tv*/,
+ const char */*excuse*/, va_list */*ap*/);
/* --- @tvec_fail@, @tvec_fail_v@ --- *
*
* safely be left null if the test function is run only once.
*/
-extern void PRINTF_LIKE(2, 3)
- tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
+extern PRINTF_LIKE(2, 3)
+ void tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
extern void tvec_fail_v(struct tvec_state */*tv*/,
const char */*detail*/, va_list */*ap*/);
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @unsigned disp@ = the register disposition (@TVRD_...@)
- * @const union tvec_regval *tv@ = register value
+ * @const union tvec_regval *tv@ = register value, or null
* @const struct tvec_regdef *rd@ = register definition
*
* Returns: ---
unsigned /*disp*/, const union tvec_regval */*rv*/,
const struct tvec_regdef */*rd*/);
+/* --- @tvec_initregs@, @tvec_releaseregs@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: ---
+ *
+ * Use: Initialize or release, respectively, the registers required
+ * by the current test. All of the registers, both input and
+ * output, are effected. Initialized registers are not marked
+ * live.
+ */
+
+extern void tvec_initregs(struct tvec_state */*tv*/);
+extern void tvec_releaseregs(struct tvec_state */*tv*/);
+
+/* --- @tvec_resetoutputs@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: ---
+ *
+ * Use: Reset (releases and reinitializes) the output registers in
+ * the test state. This is mostly of use to test environment
+ * @run@ functions, between invocations of the test function.
+ * Output registers are marked live if and only if the
+ * corresponding input register is live.
+ */
+
+extern void tvec_resetoutputs(struct tvec_state */*tv*/);
+
+/* --- @tvec_checkregs@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: Zero on success, %$-1$% on mismatch.
+ *
+ * Use: Compare the active output registers (according to the current
+ * test group definition) with the corresponding input register
+ * values. A mismatch occurs if the two values differ
+ * (according to the register type's @eq@ method), or if the
+ * input is live but the output is dead.
+ *
+ * This function only checks for a mismatch and returns the
+ * result; it takes no other action. In particular, it doesn't
+ * report a failure, or dump register values.
+ */
+
+extern int tvec_checkregs(struct tvec_state */*tv*/);
+
/* --- @tvec_mismatch@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* obvious way.
*/
-extern void PRINTF_LIKE(2, 3)
- tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
+extern PRINTF_LIKE(2, 3)
+ void tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
extern void tvec_check_v(struct tvec_state */*tv*/,
const char */*detail*/, va_list */*ap*/);
#define TVEC_BEGINTEST(tv) \
do tvec_begintest(tv, __FILE__, __LINE__); while (0)
-/* --- *tvec_endtest@ --- *
+/* --- @tvec_endtest@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
*
* Returns: ---
*
- * Use: End a ad-hoc test case, The statistics are updated and the
+ * Use: End an ad-hoc test case, The statistics are updated and the
* outcome is reported to the output formatter.
*/
* the failure message.
*/
-extern int PRINTF_LIKE(5, 6)
- tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
- const char */*file*/, unsigned /*lno*/,
- const char */*msg*/, ...);
+extern PRINTF_LIKE(5, 6)
+ int tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*msg*/, ...);
extern int tvec_claim_v(struct tvec_state */*tv*/, int /*ok*/,
const char */*file*/, unsigned /*lno*/,
const char */*msg*/, va_list */*ap*/);
/*----- Benchmarking ------------------------------------------------------*/
-struct tvec_bench {
+struct tvec_benchenv {
struct tvec_env _env; /* benchmarking is an environment */
struct bench_state **bst; /* benchmark state anchor or null */
unsigned long niter; /* iterations done per unit */
int riter, rbuf; /* iterations and buffer registers */
const struct tvec_env *env; /* subordinate environment */
};
-#define TVEC_BENCHENV \
- { sizeof(struct tvec_benchctx), \
- tvec_benchsetup, \
- tvec_benchset, \
- tvec_benchbefore, \
- tvec_benchrun, \
- tvec_benchafter, \
- tvec_benchteardown }
-#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
struct tvec_benchctx {
- const struct tvec_bench *b;
- struct bench_state *bst;
- double dflt_target;
- void *subctx;
+ const struct tvec_benchenv *be; /* environment configuration */
+ struct bench_state *bst; /* benchmark state */
+ double dflt_target; /* default time in seconds */
+ unsigned f; /* flags */
+#define TVBF_SETTRG 1u /* set `@target' */
+#define TVBF_SETMASK (TVBF_SETTRG)) /* mask of @TVBF_SET...@ */
+ void *subctx; /* subsidiary environment context */
};
extern struct bench_state *tvec_benchstate;
-/* --- @tvec_benchsetup@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test vector state
- * @const struct tvec_env *env@ = environment description
- * @void *pctx@ = parent context (ignored)
- * @void *ctx@ = context pointer to initialize
+/* --- Environment implementation --- *
*
- * Returns: Zero on success, @-1@ on failure.
+ * The following special variables are supported.
*
- * Use: Initialize a benchmarking environment context.
+ * * %|@target|% is the (approximate) number of seconds to run the
+ * benchmark.
*
- * The environment description must really be a @struct
- * tvec_bench@. If the @bst@ slot is null, then a temporary
- * benchmark state is allocated for the current test group and
- * released at the end. Otherwise, it must be the address of a
- * pointer to a benchmark state: if the pointer is null, then a
- * fresh state is allocated and initialized and the pointer is
- * updated; otherwise, the pointer is assumed to refer to an
- * existing valid benchmark state.
+ * Unrecognized variables are passed to the subordinate environment, if there
+ * is one. Other events are passed through to the subsidiary environment.
*/
-extern int tvec_benchsetup(struct tvec_state */*tv*/,
- const struct tvec_env */*env*/,
- void */*pctx*/, void */*ctx*/);
+extern tvec_envsetupfn tvec_benchsetup;
+extern tvec_envfindvarfn tvec_benchfindvar;
+extern tvec_envbeforefn tvec_benchbefore;
+extern tvec_envrunfn tvec_benchrun;
+extern tvec_envafterfn tvec_benchafter;
+extern tvec_envteardownfn tvec_benchteardown;
-/* --- @tvec_benchset@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test vector state
- * @const char *var@ = variable name to set
- * @const struct tvec_env *env@ = environment description
- * @void *ctx@ = context pointer
- *
- * Returns: Zero on success, @-1@ on failure.
+#define TVEC_BENCHENV \
+ { sizeof(struct tvec_benchctx), \
+ tvec_benchsetup, \
+ tvec_benchfindvar, \
+ tvec_benchbefore, \
+ tvec_benchrun, \
+ tvec_benchafter, \
+ tvec_benchteardown }
+#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
+
+/* --- @tvec_benchreport@ --- *
*
- * Use: Set a special variable. The following special variables are
- * supported.
+ * Arguments: @const struct gprintf_ops *gops@ = print operations
+ * @void *go@ = print destination
+ * @unsigned unit@ = the unit being measured (~TVBU_...@)
+ * @const struct bench_timing *tm@ = the benchmark result
*
- * * %|@target|% is the (approximate) number of seconds to run
- * the benchmark.
+ * Returns: ---
*
- * Unrecognized variables are passed to the subordinate
- * environment, if there is one.
+ * Use: Formats a report about the benchmark performance. This
+ * function is intended to be called on by an output
+ * @ebench@ function.
*/
-extern int tvec_benchset(struct tvec_state */*tv*/, const char */*var*/,
- const struct tvec_env */*env*/, void */*ctx*/);
+extern void tvec_benchreport
+ (const struct gprintf_ops */*gops*/, void */*go*/,
+ unsigned /*unit*/, const struct bench_timing */*tm*/);
+
+/*----- Remote execution --------------------------------------------------*/
-/* --- @tvec_benchbefore@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test vector state
- * @void *ctx@ = context pointer
- *
- * Returns: Zero on success, @-1@ on failure.
- *
- * Use: Invoke the subordinate environment's @before@ function to
- * prepare for the benchmark.
- */
+struct tvec_remotecomms {
+ int infd, outfd; /* input and output descriptors */
+ dbuf bout; /* output buffer */
+ unsigned char *bin; /* input buffer */
+ size_t binoff, binlen, binsz; /* input offset, length, and size */
+ size_t t; /* temporary offset */
+ unsigned f; /* flags */
+#define TVRF_BROKEN 0x0001u /* communications have failed */
+};
+#define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, 0, 0, 0, 0, 0, 0 }
+
+struct tvec_remotectx {
+ struct tvec_state *tv; /* test vector state */
+ struct tvec_remotecomms rc; /* communication state */
+ const struct tvec_remoteenv *re; /* environment configuration */
+ void *subctx; /* subenvironment context */
+ struct tvec_vardef vd; /* temporary variable definition */
+ unsigned ver; /* protocol version */
+ pid_t kid; /* child process id */
+ int errfd; /* child stderr descriptor */
+ lbuf errbuf; /* child stderr line buffer */
+ dstr prgwant, progress; /* progress: wanted/reported */
+ unsigned exwant, exit; /* exit status wanted/reported */
+#define TVRF_RCNMASK 0x0300u /* reconnection behaviour: */
+#define TVRCN_DEMAND 0x0000u /* connect on demand */
+#define TVRCN_SKIP 0x0100u /* skip unless connected */
+#define TVRCN_FORCE 0x0200u /* force reconnection */
+#define TVRF_MUFFLE 0x0400u /* muffle child stderr */
+#define TVRF_SETEXIT 0x0800u /* set `@exit' */
+#define TVRF_SETPRG 0x1000u /* set `@progress' */
+#define TVRF_SETRCN 0x2000u /* set `@reconnect' */
+#define TVRF_SETMASK (TVRF_SETEXIT | TVRF_SETPRG | TVRF_SETRCN)
+ /* mask of @TVTF_SET...@ */
+};
+
+typedef int tvec_connectfn(pid_t */*kid_out*/, int */*infd_out*/,
+ int */*outfd_out*/, int */*errfd_out*/,
+ struct tvec_state */*tv*/,
+ const struct tvec_remoteenv */*env*/);
+ /* A connection function. On entry, @tv@ holds the test-vector state, and
+ * @env@ is the test group's remote environment structure, which will
+ * typically really be some subclass of @struct tvec_remoteenv@ containing
+ * additional parameters for establishing the child process.
+ *
+ * On successful completion, the function stores input and output
+ * descriptors (which need not be distinct) in @*infd_out@ and
+ * @*outfd_out@, and returns zero; if it creates a child process, it should
+ * additionally store the child's process-id in @*kid_out@ and store in
+ * @*errfd_out@ a descriptor from which the child's error output can be
+ * read. On error, the function should report an appropriate message via
+ * @tvec_error@ and return %$-1$%.
+ */
-extern int tvec_benchbefore(struct tvec_state */*tv*/, void */*ctx*/);
+struct tvec_remoteenv_slots {
+ tvec_connectfn *connect; /* connection function */
+ const struct tvec_env *env; /* subsidiary environment */
+ unsigned dflt_reconn; /* default reconnection */
+};
-/* --- @tvec_benchrun@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test vector state
- * @tvec_testfn *fn@ = test function to run
- * @void *ctx@ = context pointer for the test function
+struct tvec_remoteenv {
+ struct tvec_env _env;
+ struct tvec_remoteenv_slots r;
+};
+
+struct tvec_remotefork_slots {
+ const struct tvec_test *tests; /* child tests (or null) */
+};
+
+struct tvec_remotefork {
+ struct tvec_env _env;
+ struct tvec_remoteenv_slots r;
+ struct tvec_remotefork_slots f;
+};
+
+struct tvec_remoteexec_slots {
+ const char *const *args; /* command line to execute */
+};
+
+struct tvec_remoteexec {
+ struct tvec_env _env;
+ struct tvec_remoteenv_slots r;
+ struct tvec_remoteexec_slots x;
+};
+
+union tvec_remoteenv_subclass_kludge {
+ struct tvec_env _env;
+ struct tvec_remoteenv renv;
+ struct tvec_remotefork fork;
+ struct tvec_remoteexec exec;
+};
+
+/* Exit status.
+ *
+ * We don't use the conventional encoding returned by the @wait@(2) family of
+ * system calls because it's too hard for our flags type to decode. Instead,
+ * we use our own encoding.
+ *
+ * The exit code or signal number ends up in the `value' field in the low 12
+ * bits; bit 12 is set if the value field holds a signal, and it if holds an
+ * exit code. Bits 13--15 hold a code which describes the status of a child
+ * process or connection.
+ */
+#define TVXF_VALMASK 0x0fffu /* value (exit code or signal) */
+#define TVXF_SIG 0x1000u /* value is signal, not exit code */
+#define TVXF_CAUSEMASK 0xe000u /* mask for cause bits */
+#define TVXST_RUN 0x0000u /* still running */
+#define TVXST_EXIT 0x2000u /* child exited */
+#define TVXST_KILL 0x4000u /* child killed by signal */
+#define TVXST_CONT 0x6000u /* child continued (?) */
+#define TVXST_STOP 0x8000u /* child stopped (?) */
+#define TVXST_DISCONN 0xa000u /* disconnected */
+#define TVXST_UNK 0xc000u /* unknown */
+#define TVXST_ERR 0xe000u /* local error prevented diagnosis */
+
+/* Remote environment. */
+extern tvec_envsetupfn tvec_remotesetup;
+extern tvec_envfindvarfn tvec_remotefindvar;
+extern tvec_envbeforefn tvec_remotebefore;
+extern tvec_envrunfn tvec_remoterun;
+extern tvec_envafterfn tvec_remoteafter;
+extern tvec_envteardownfn tvec_remoteteardown;
+#define TVEC_REMOTEENV \
+ { sizeof(struct tvec_remotectx), \
+ tvec_remotesetup, \
+ tvec_remotefindvar, \
+ tvec_remotebefore, \
+ tvec_remoterun, \
+ tvec_remoteafter, \
+ tvec_remoteteardown }
+
+/* --- @tvec_setprogress@, @tvec_setprogress_v@ --- *
+ *
+ * Arguments: @const char *status@ = progress status token format
+ * @va_list ap@ = argument tail
*
* Returns: ---
*
- * Use: Measures and reports the performance of a test function.
+ * Use: Reports the progress of a test execution to the client.
*
+ * The framework makes use of tokens beginning with %|%|%:
*
- */
-
-extern void tvec_benchrun(struct tvec_state */*tv*/,
- tvec_testfn */*fn*/, void */*ctx*/);
-
-/* --- @tvec_benchafter@ --- *
+ * * %|%IDLE|%: during the top-level server code;
*
- * Arguments: @struct tvec_state *tv@ = test vector state
- * @void *ctx@ = context pointer
+ * * %|%SETUP|%: during the enclosing environment's @before@
+ * function;
*
- * Returns: ---
+ * * %|%RUN|%: during the environment's @run@ function, or the
+ * test function; and
+ *
+ * * %|%DONE|%: during the enclosing environment's @after@
+ * function.
*
- * Use: Invoke the subordinate environment's @after@ function to
- * clean up after the benchmark.
+ * The intent is that a test can use the progress token to check
+ * that a function which is expected to crash does so at the
+ * correct point, so it's expected that more complex test
+ * functions and/or environments will set their own progress
+ * tokens to reflect what's going on.
*/
-extern void tvec_benchafter(struct tvec_state */*tv*/, void */*ctx*/);
+extern PRINTF_LIKE(1, 2) int tvec_setprogress(const char */*status*/, ...);
+extern int tvec_setprogress_v(const char */*status*/, va_list */*ap*/);
-/* --- @tvec_benchteardown@ --- *
+/* --- @tvec_remoteserver@ --- *
*
- * Arguments: @struct tvec_state *tv@ = test vector state
- * @void *ctx@ = context pointer
+ * Arguments: @int infd@, @int outfd@ = input and output file descriptors
+ * @const struct tvec_config *config@ = test configuration
*
- * Returns: ---
+ * Returns: Suggested exit code.
+ *
+ * Use: Run a test server, reading packets from @infd@ and writing
+ * responses and notifications to @outfd@, and invoking tests as
+ * described by @config@.
*
- * Use: Tear down the benchmark environment.
+ * This function is not particularly general purpose. It
+ * expects to `take over' the process, and makes use of private
+ * global variables.
*/
-extern void tvec_benchteardown(struct tvec_state */*tv*/, void */*ctx*/);
+extern int tvec_remoteserver(int /*infd*/, int /*outfd*/,
+ const struct tvec_config */*config*/);
-/* --- @tvec_benchreport@ --- *
+extern tvec_connectfn tvec_fork, tvec_exec;
+
+#define TVEC_REMOTEFORK(subenv, tests) \
+ TVEC_REMOTEENV, { tvec_fork, subenv }, { tests }
+
+#define TVEC_REMOTEEXEC(subenv, args) \
+ TVEC_REMOTEENV, { tvec_exec, subenv }, { args }
+
+/*----- Timeouts ----------------------------------------------------------*/
+
+struct tvec_timeoutenv {
+ struct tvec_env _env;
+ int timer; /* the timer (@ITIMER_...@) */
+ double t; /* time to wait (in seconds) */
+ const struct tvec_env *env; /* subsidiary environment */
+};
+
+struct tvec_timeoutctx {
+ const struct tvec_timeoutenv *te; /* saved environment description */
+ int timer; /* timer code (as overridden) */
+ double t; /* time to wait (as overridden) */
+ unsigned f; /* flags */
+#define TVTF_SETTMO 1u /* set `@timeout' */
+#define TVTF_SETTMR 2u /* set `@timer' */
+#define TVTF_SETMASK (TVTF_SETTMO | TVTF_SETTMR)
+ /* mask of @TVTF_SET...@ */
+ void *subctx;
+};
+
+extern tvec_envsetupfn tvec_timeoutsetup;
+extern tvec_envfindvarfn tvec_timeoutfindvar;
+extern tvec_envbeforefn tvec_timeoutbefore;
+extern tvec_envrunfn tvec_timeoutrun;
+extern tvec_envafterfn tvec_timeoutafter;
+extern tvec_envteardownfn tvec_timeoutteardown;
+#define TVEC_TIMEOUTENV \
+ { sizeof(struct tvec_timeoutctx), \
+ tvec_timeoutsetup, \
+ tvec_timeoutfindvar, \
+ tvec_timeoutbefore, \
+ tvec_timeoutrun, \
+ tvec_timeoutafter, \
+ tvec_timeoutteardown }
+#define TVEC_TIMEOUTINIT(timer, t) TVEC_TIMEOUTENV, timer, t
+
+/*----- Output functions --------------------------------------------------*/
+
+/* --- @tvec_strlevel@ --- *
*
- * Arguments: @const struct gprintf_ops *gops@ = print operations
- * @void *go@ = print destination
- * @unsigned unit@ = the unit being measured (~TVBU_...@)
- * @const struct bench_timing *tm@ = the benchmark result
+ * Arguments: @unsigned level@ = level code
*
- * Returns: ---
+ * Returns: A human-readable description.
*
- * Use: Formats a report about the benchmark performance. This
- * function is intended to be called on by an output
- * @ebench@ function.
+ * Use: Converts a level code into something that you can print in a
+ * message.
*/
-extern void tvec_benchreport
- (const struct gprintf_ops */*gops*/, void */*go*/,
- unsigned /*unit*/, const struct bench_timing */*tm*/);
-
-/*----- Output functions --------------------------------------------------*/
+extern const char *tvec_strlevel(unsigned /*level*/);
-/* --- @tvec_error@, @tvec_error_v@ --- *
+/* --- @tvec_report@, @tvec_report_v@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @const char *msg@, @va_list ap@ = error message
*
- * Returns: @-1@.
+ * Returns: ---
*
- * Use: Report an error. Errors are distinct from test failures,
- * and indicate that a problem was encountered which compromised
- * the activity of testing.
+ * Use: Report an message with a given severity. Messages with level
+ * @TVLEV_ERR@ or higher force a nonzero exit code.
*/
-extern int PRINTF_LIKE(2, 3)
- tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
-extern int tvec_error_v(struct tvec_state */*tv*/,
- const char */*msg*/, va_list */*ap*/);
+extern PRINTF_LIKE(3, 4)
+ void tvec_report(struct tvec_state */*tv*/, unsigned /*level*/,
+ const char */*msg*/, ...);
+extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
+ const char */*msg*/, va_list */*ap*/);
-/* --- @tvec_notice@, @tvec_notice_v@ --- *
+/* --- @tvec_error@, @tvec_notice@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
- * @const char *msg@, @va_list ap@ = message
+ * @const char *msg@, @va_list ap@ = error message
*
- * Returns: ---
+ * Returns: The @tvec_error@ function returns %$-1$% as a trivial
+ * convenience; @tvec_notice@ does not return a value.
*
- * Use: Output a notice: essentially, some important information
- * which doesn't fit into any of the existing categories.
+ * Use: Report an error or a notice. Errors are distinct from test
+ * failures, and indicate that a problem was encountered which
+ * compromised the activity of testing. Notices are important
+ * information which doesn't fit into any other obvious
+ * category.
*/
-extern void PRINTF_LIKE(2, 3)
- tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
-extern void tvec_notice_v(struct tvec_state */*tv*/,
- const char */*msg*/, va_list */*ap*/);
+extern PRINTF_LIKE(2, 3)
+ int tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
+extern PRINTF_LIKE(2, 3)
+ void tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
/* --- @tvec_humanoutput@ --- *
*
* (`Test Anything Protocol') format.
*
* TAP comes from the Perl community, but has spread rather
- * further. This driver produces TAP version 13. The driver
- * produces a TAP `test point' -- i.e., a result reported as
- * `ok' or `not ok' -- for each input test group. Failure
- * reports and register dumps are produced as diagnostic
- * messages before the final group result. (TAP permits
- * structuerd YAML data after the test-point result, which could
- * be used to report details, but (a) postponing the details
- * until after the report is inconvenient, and (b) there is no
- * standardization for the YAML anyway, so in practice it's no
- * more useful than the unstructured diagnostics.
+ * further. This driver produces TAP version 14, but pretends
+ * to be version 13. The driver produces a TAP `test point' --
+ * i.e., a result reported as `ok' or `not ok' -- for each input
+ * test group. Failure reports and register dumps are produced
+ * as diagnostic messages before the final group result. (TAP
+ * permits structuerd YAML data after the test-point result,
+ * which could be used to report details, but (a) postponing the
+ * details until after the report is inconvenient, and (b) there
+ * is no standardization for the YAML anyway, so in practice
+ * it's no more useful than the unstructured diagnostics.
*/
extern struct tvec_output *tvec_tapoutput(FILE */*fp*/);
/*------ Serialization utilities ------------------------------------------*/
+/* Serialization format.
+ *
+ * The `candidate register definitions' are those entries @r@ in the @regs@
+ * vector whose index @r.i@ is strictly less than @nr@. The `selected
+ * register definitions' are those candidate register definitions @r@ for
+ * which the indicated register @rv[r.i]@ has the @TVRF_LIVE@ flag set. The
+ * serialized output begins with a header bitmap: if there are %$n$%
+ * candidate register definitions then the header bitmap consists of %$\lceil
+ * n/8 \rceil$% bytes. Bits are ordered starting from the least significant
+ * bit of the first byte, end ending at the most significant bit of the final
+ * byte. The bit corresponding to a candidate register definition is set if
+ * and only if that register defintion is selected. The header bitmap is
+ * then followed by the serializations of the selected registers -- i.e., for
+ * each selected register definition @r@, the serialized value of register
+ * @rv[r.i]@ -- simply concatenated together, with no padding or alignment.
+ */
+
/* --- @tvec_serialize@ --- *
*
* Arguments: @const struct tvec_reg *rv@ = vector of registers
* @unsigned nr@ = number of entries in the @rv@ vector
* @size_t regsz@ = true size of each element of @rv@
*
- * Returns: Zero on success, @-1@ on failure.
+ * Returns: Zero on success, %$-1$% on failure.
*
* Use: Serialize a collection of register values.
*
- * The `candidate register definitions' are those entries @r@ in
- * the @regs@ vector whose index @r.i@ is strictly less than
- * @nr@. The `selected register definitions' are those
- * candidate register definitions @r@ for which the indicated
- * register @rv[r.i]@ has the @TVRF_LIVE@ flag set. The
- * serialized output begins with a header bitmap: if there are
- * %$n$% candidate register definitions then the header bitmap
- * consists of %$\lceil n/8 \rceil$% bytes. Bits are ordered
- * starting from the least significant bit of the first byte,
- * end ending at the most significant bit of the final byte.
- * The bit corresponding to a candidate register definition is
- * set if and only if that register defintion is selected. The
- * header bitmap is then followed by the serializations of the
- * selected registers -- i.e., for each selected register
- * definition @r@, the serialized value of register @rv[r.i]@ --
- * simply concatenated together, with no padding or alignment.
- *
* The serialized output is written to the buffer @b@. Failure
* can be caused by running out of buffer space, or a failing
* type handler.
* @unsigned nr@ = number of entries in the @rv@ vector
* @size_t regsz@ = true size of each element of @rv@
*
- * Returns: Zero on success, @-1@ on failure.
+ * Returns: Zero on success, %$-1$% on failure.
*
* Use: Deserialize a collection of register values.
*
* slot, and set the @TVRF_LIVE@ flag on the register. See
* @tvec_serialize@ for a description of the format.
*
- * On successful completion, store the address of the first byte
- * after the serialized data in @*end_out@ if @end_out@ is not
- * null. Failure results only from a failing register type
- * handler.
+ * Failure results only from a failing register type handler.
*/
extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
* current line number.
*/
-/* --- @tvec_skipspc@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- *
- * Returns: ---
- *
- * Use: Advance over any whitespace characters other than newlines.
- * This will stop at `;', end-of-file, or any other kind of
- * non-whitespace; and it won't consume a newline.
- */
-
-extern void tvec_skipspc(struct tvec_state */*tv*/);
-
/* --- @tvec_syntax@, @tvec_syntax_v@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @int ch@ = the character found (in @fgetc@ format)
* @const char *expect@, @va_list ap@ = what was expected
*
- * Returns: @-1@
+ * Returns: %$-1$%.
*
* Use: Report a syntax error quoting @ch@ and @expect@. If @ch@ is
* a newline, then back up so that it can be read again (e.g.,
* advance the line number).
*/
-extern int PRINTF_LIKE(3, 4)
- tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
- const char */*expect*/, ...);
+extern PRINTF_LIKE(3, 4)
+ int tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
+ const char */*expect*/, ...);
extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
const char */*expect*/, va_list */*ap*/);
+/* --- @tvec_unkreg@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *name@ = register or pseudoregister name
+ *
+ * Returns: %$-1$%.
+ *
+ * Use: Reports an error that the register or pseudoregister is
+ * unrecognized.
+ */
+
+extern int tvec_unkreg(struct tvec_state */*tv*/, const char */*name*/);
+
+/* --- @tvec_dupreg@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *name@ = register or pseudoregister name
+ *
+ * Returns: %$-1$%.
+ *
+ * Use: Reports an error that the register or pseudoregister has been
+ * assigned already in the current test.
+ */
+
+extern int tvec_dupreg(struct tvec_state */*tv*/, const char */*name*/);
+
+/* --- @tvec_skipspc@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: ---
+ *
+ * Use: Advance over any whitespace characters other than newlines.
+ * This will stop at `;', end-of-file, or any other kind of
+ * non-whitespace; and it won't consume a newline.
+ */
+
+extern void tvec_skipspc(struct tvec_state */*tv*/);
+
/* --- @tvec_flushtoeol@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @unsigned f@ = flags (@TVFF_...@)
*
- * Returns: Zero on success, @-1@ on error.
+ * Returns: Zero on success, %$-1$% on error.
*
* Use: Advance to the start of the next line, consuming the
* preceding newline.
*
* Arguments: @struct tvec_state *tv@ = test-vector state
*
- * Returns: Zero if there is a next token which can be read; @-1@ if no
+ * Returns: Zero if there is a next token which can be read; %$-1$% if no
* token is available.
*
* Use: Advance to the next whitespace-separated token, which may be
*
* If this function returns zero, then the next character in the
* file begins a suitable token which can be read and
- * processed. If it returns @-1@ then there is no such token,
+ * processed. If it returns %$-1$% then there is no such token,
* and the file position is left correctly. The line number
* count is updated appropriately.
*/
extern int tvec_nexttoken(struct tvec_state */*tv*/);
-/* --- @tvec_readword@ --- *
+/* --- @tvec_readword@, @tvec_readword_v@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @dstr *d@ = string to append the word to
+ * @const char **p_inout@ = pointer into string, updated
* @const char *delims@ = additional delimiters to stop at
* @const char *expect@, @va_list ap@ = what was expected
*
- * Returns: Zero on success, @-1@ on failure.
+ * Returns: Zero on success, %$-1$% on failure.
*
* Use: A `word' consists of characters other than whitespace, null
* characters, and other than those listed in @delims@;
* include `;' in @delims@. This is a common behaviour.)
*
* If there is no word beginning at the current file position,
- * then return @-1@; furthermore, if @expect@ is not null, then
- * report an appropriate error via @tvec_syntax@.
+ * then return %$-1$%; furthermore, if @expect@ is not null,
+ * then report an appropriate error via @tvec_syntax@.
*
* Otherwise, the word is accumulated in @d@ and zero is
* returned; if @d@ was not empty at the start of the call, the
* word constituents, a null terminator is written to @d@, and
* it is safe to treat the string in @d@ as being null-
* terminated.
+ *
+ * If @p_inout@ is not null, then @*p_inout@ must be a pointer
+ * into @d->buf@, which will be adjusted so that it will
+ * continue to point at the same position even if the buffer is
+ * reallocated. As a subtle tweak, if @*p_inout@ initially
+ * points at the end of the buffer, then it will be adjusted to
+ * point at the beginning of the next word, rather than at the
+ * additional intervening space.
*/
-extern int PRINTF_LIKE(4, 5)
- tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
- const char */*delims*/, const char */*expect*/, ...);
+extern PRINTF_LIKE(5, 6)
+ int tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
+ const char **/*p_inout*/, const char */*delims*/,
+ const char */*expect*/, ...);
extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
- const char */*delims*/, const char */*expect*/,
- va_list */*ap*/);
+ const char **/*p_inout*/, const char */*delims*/,
+ const char */*expect*/, va_list */*ap*/);
/*----- Integer types: signed and unsigned --------------------------------*/
/*----- Floating-point type -----------------------------------------------*/
-/* Floating-point are either NaN (`#nan', if supported by the platform);
- * positive or negative infinity (`#inf', `+#inf', or, preferred, `#+inf',
- * and `-#inf' or, preferred, `#-inf', if supported by the platform), or a
- * number in strtod(3) syntax.
+/* Floating-point values are either NaN (%|#nan|%, if supported by the
+ * platform); positive or negative infinity (%|#inf|%, %|+#inf|%, or
+ * %|#+inf|% (preferring the last), and %|-#inf|% or %|#-inf|% (preferring
+ * the latter), if supported by the platform); or a number in strtod(3)
+ * syntax.
*
* The comparison rules for floating-point numbers are complex: see
* @tvec_claimeqish_float@ for details.
#define TVEC_CLAIMEQ_FLOAT(tv, f0, f1) \
(tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))
+extern const struct tvec_floatinfo tvflt_finite, tvflt_nonneg;
+
+/*----- Durations ---------------------------------------------------------*/
+
+/* A duration measures a time interval in seconds. The input format consists
+ * of a nonnegative decimal floating-point number in @strtod@ format followed
+ * by an optional unit specification.
+ *
+ * No @tvec_claimeq_...@ function is provided for durations: use
+ * @tvec_claimeq_float@.
+ */
+
+extern const struct tvec_regty tvty_duration;
+
/*----- Enumerated types --------------------------------------------------*/
/* An enumeration describes a set of values of some underlying type, each of
* On input, an enumerated value may be given by name or as a literal value.
* For enumerations based on numeric types, the literal values can be written
* in the same syntax as the underlying values. For enumerations based on
- * pointers, the only permitted literal is `#nil', which denotes a null
+ * pointers, the only permitted literal is %|#nil|%, which denotes a null
* pointer. On output, names are preferred (with the underlying value given
* in a comment).
*/
#undef DEFINFO
/* Standard enumerations. */
-const struct tvec_ienuminfo tvenum_bool;
+extern const struct tvec_ienuminfo tvenum_bool;
+extern const struct tvec_ienuminfo tvenum_cmp;
/* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
*
* fields; more precisely, each name is associated with a value and a
* covering bitmask.
*
- * The input syntax is a sequence of items separated by `|' signs. Each item
- * may be the symbolic name of a field value, or a literal unsigned integer.
- * The masks associated with the given symbolic names must be disjoint. The
- * resulting numerical value is simply the bitwise OR of the given values.
+ * The input syntax is a sequence of items separated by `%|||%' signs. Each
+ * item may be the symbolic name of a field value, or a literal unsigned
+ * integer. The masks associated with the given symbolic names must be
+ * disjoint. The resulting numerical value is simply the bitwise OR of the
+ * given values.
*
* On output, the table of symbolic names and their associated values and
* masks is repeatedly scanned, in order, to find disjoint matches -- i.e.,
* entries whose value matches the target value in the bit positions
* indicated by the mask, and whose mask doesn't overlap with any previously
- * found matches; the names are then output, separated by `|'. Any remaining
- * nonzero bits not covered by any of the matching masks are output as a
- * single literal integer, in hex.
+ * found matches; the names are then output, separated by `%|||%'. Any
+ * remaining nonzero bits not covered by any of the matching masks are output
+ * as a single literal integer, in hex.
*/
extern const struct tvec_regty tvty_flags;
/* A character value holds a character, as read by @fgetc@. The special
* @EOF@ value can also be represented.
*
- * On input, a character value can be given by name, with a leading `%|#|%';
- * or a character or `%|\|%'-escape sequence, optionally in single quotes.
+ * On input, a character value can be given by symbolic name, with a leading
+ * `%|#|%'; or a character or `%|\|%'-escape sequence, optionally in single
+ * quotes.
*
* The following escape sequences and character names are recognized.
*
* * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes
* %$n$% copies of the (compound) string.
*
+ * The only difference between text and binary strings is that the initial
+ * coding scheme is %|bare|% for text strings and %|hex|% for binary strings.
+ *
* Either kind of string can contain internal nul characters. A trailing nul
* is appended -- beyond the stated input length -- to input strings as a
* convenience to test functions. Test functions may include such a nul
* string (in bytes) will be checked against the permitted range.
*/
-extern const struct tvec_regty tvty_string, tvty_bytes;
+extern const struct tvec_regty tvty_text, tvty_bytes;
-/* --- @tvec_claimeq_string@, @TVEC_CLAIMEQ_STRING@ --- *
+/* --- @tvec_claimeq_text@, @TVEC_CLAIMEQ_TEXT@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @const char *p0@, @size_t sz0@ = first string with length
* mismatched values are dumped: @p0@ is printed as the output
* value and @p1@ is printed as the input reference.
*
- * The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
+ * The @TVEC_CLAIM_TEXT@ macro is similar, only it (a)
* identifies the file and line number of the call site
* automatically, and (b) implicitly quotes the source text of
* the @ch0@ and @ch1@ arguments in the failure message.
*/
-extern int tvec_claimeq_string(struct tvec_state */*tv*/,
- const char */*p0*/, size_t /*sz0*/,
- const char */*p1*/, size_t /*sz1*/,
- const char */*file*/, unsigned /*lno*/,
- const char */*expr*/);
-#define TVEC_CLAIMEQ_STRING(tv, p0, sz0, p1, sz1) \
- (tvec_claimeq_string(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
- #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
+extern int tvec_claimeq_text(struct tvec_state */*tv*/,
+ const char */*p0*/, size_t /*sz0*/,
+ const char */*p1*/, size_t /*sz1*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQ_TEXT(tv, p0, sz0, p1, sz1) \
+ (tvec_claimeq_text(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
+ #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
-/* --- @tvec_claimeq_strz@, @TVEC_CLAIMEQ_STRZ@ --- *
+/* --- @tvec_claimeq_textz@, @TVEC_CLAIMEQ_TEXTZ@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @const char *p0, *p1@ = two strings to compare
* Use: Check that strings at @p0@ and @p1@ are equal, as for
* @tvec_claimeq_string@, except that the strings are assumed
* null-terminated, so their lengths don't need to be supplied
- * explicitly. The macro is similarly like
- * @TVEC_CLAIMEQ_STRING@.
+ * explicitly. The macro is similarly like @TVEC_CLAIMEQ_TEXT@.
*/
-extern int tvec_claimeq_strz(struct tvec_state */*tv*/,
- const char */*p0*/, const char */*p1*/,
- const char */*file*/, unsigned /*lno*/,
- const char */*expr*/);
-#define TVEC_CLAIMEQ_STRZ(tv, p0, p1) \
- (tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
+extern int tvec_claimeq_textz(struct tvec_state */*tv*/,
+ const char */*p0*/, const char */*p1*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQ_TEXTZ(tv, p0, p1) \
+ (tvec_claimeq_textz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
/* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- *
*
(tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
#p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
-/* --- @tvec_allocstring@, @tvec_allocbytes@ --- *
+/* --- @tvec_alloctext@, @tvec_allocbytes@ --- *
*
* Arguments: @union tvec_regval *rv@ = register value
* @size_t sz@ = required size
* the old buffer contents are simply discarded if reallocation
* is necessary. Instead, use a @dbuf@ or @dstr@.
*
- * The @tvec_allocstring@ function sneakily allocates an extra
+ * The @tvec_alloctext@ function sneakily allocates an extra
* byte for a terminating zero. The @tvec_allocbytes@ function
* doesn't do this.
*/
-extern void tvec_allocstring(union tvec_regval */*rv*/, size_t /*sz*/);
+extern void tvec_alloctext(union tvec_regval */*rv*/, size_t /*sz*/);
extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
/*----- Buffer type -------------------------------------------------------*/
/* Buffer registers are primarily used for benchmarking. Only a buffer's
- * size is significant: its contents are ignored on comparison and output,
- * and unspecified on input.
+ * allocation parameters are significant: its contents are ignored on
+ * comparison and output, and unspecified on input.
+ *
+ * The input format gives the buffer's size, and an optional alignment
+ * specification, in the form %|SZ [`@' M [`+' A]]|%. Each of %|SZ|%, %|M|%
+ * and %|A|% are sizes, as an integer, optionally suffixed with a unit `kB',
+ * `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or without the `B')
+ * denoting a power of 1024. The %|SZ|% gives the (effective) buffer size.
+ * %|M|% is the `alignment quantum' and %|A|% is the `alignment offset'; both
+ * default to zero, but if %|M|% is nonzero then the start of the buffer is
+ * aligned such that it is %|A|% more than a multiple of %|M|% bytes. Note
+ * that %|M|% need not be a power of two, though this is common.
+ *
+ * Units other than `B' are used on output only when the size would be
+ * expressed exactly.
+ *
+ * Buffers are %%\emph{not}%% allocated by default. In benchmarks, this is
+ * best done in a @before@ function.
*
- * The input is simply the buffer size, as an integer, optionally suffixed
- * with a unit `kB', `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or
- * without the `B') denoting a power of 1024. Units are used on output only
- * when the size would be expressed exactly.
+ * No @claimeq@ functions or macros are provided for buffers because they
+ * don't seem very useful.
*/
extern const struct tvec_regty tvty_buffer;
+/* --- @tvec_initbuffer@ --- *
+ *
+ * Arguments: @union tvec_regval *rv@ = register value
+ * @const union tvec_regval *src@ = source buffer
+ * @size_t sz@ = size to allocate
+ *
+ * Returns: ---
+ *
+ * Use: Initialize the alignment parameters in @rv@ to match @src@,
+ * and the size to @sz@.
+ */
+
+extern void tvec_initbuffer(union tvec_regval */*rv*/,
+ const union tvec_regval */*src*/, size_t /*sz*/);
+
+/* --- @tvec_allocbuffer@ --- *
+ *
+ * Arguments: @union tvec_regval *rv@ = register value
+ *
+ * Returns: ---
+ *
+ * Use: Allocate @sz@ bytes to the buffer and fill the space with a
+ * distinctive pattern.
+ */
+
+extern void tvec_allocbuffer(union tvec_regval */*rv*/);
+
/*----- That's all, folks -------------------------------------------------*/
#ifdef __cplusplus