unsigned long u; /* unsigned integer */
void *p; /* pointer */
double f; /* floating point */
+ struct { char *p; size_t sz; } text; /* text string */
struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
- struct { char *p; size_t sz; } str; /* 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
*/
unsigned f; /* flags */
-#define TVRF_LIVE 1u /* used in current test */
+#define TVRF_SEEN 1u /* assignment seen in file */
+#define TVRF_LIVE 2u /* used in current test */
union tvec_regval v; /* register value */
};
*/
const char *name; /* register name (for input files) */
- unsigned i; /* register index */
const struct tvec_regty *ty; /* register type descriptor */
+ unsigned i; /* register index */
unsigned f; /* flags */
-#define TVRF_OPT 1u /* optional register */
-#define TVRF_ID 2u /* part of test identity */
+#define TVRF_UNSET 1u /* register may be marked unset */
+#define TVRF_OPT 2u /* register need not be assigned */
+#define TVRF_ID 4u /* part of test identity */
union tvec_misc arg; /* extra detail for the type */
};
#define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } }
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@.
+ * function acting on the value, including @release@. Following @init@,
+ * the register value must be valid to use for all other type entry
+ * points.
*/
void (*release)(union tvec_regval */*rv*/,
const struct tvec_regdef */*rd*/);
- /* Release any resources associated with the value in @*rv@. */
+ /* Release any resources associated with the value in @*rv@. The
+ * register value may be left in an invalid state.
+ */
int (*eq)(const union tvec_regval */*rv0*/,
const union tvec_regval */*rv1*/,
/*----- Test descriptions -------------------------------------------------*/
+struct tvec_env;
+
typedef void tvec_testfn(const struct tvec_reg */*in*/,
struct tvec_reg */*out*/,
void */*ctx*/);
* 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*/,
* will not.
*/
-typedef int tvec_envsetfn(struct tvec_state */*tv*/,
- const char */*var*/, 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.
+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.
+ * 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*/,
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, so that the test
- * environment can reset variables set by the @set@ entry point. It should
- * check the @TVSF_SKIP@ flag if necessary.
+ * %%\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*/);
size_t ctxsz; /* environment context size */
tvec_envsetupfn *setup; /* setup for group */
- tvec_envsetfn *set; /* set variable */
+ tvec_envfindvarfn *findvar; /* find variable */
tvec_envbeforefn *before; /* prepare for test */
tvec_envrunfn *run; /* run test function */
tvec_envafterfn *after; /* clean up after test */
};
#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_LIMIT /* (number of possible outcomes) */
};
+struct tvec_config {
+ /* An overall test configuration. */
+
+ const struct tvec_test *tests; /* the tests to be performed */
+ unsigned nrout, nreg; /* number of output/total regs */
+ size_t regsz; /* size of a register */
+};
+
struct tvec_state {
/* The primary state structure for the test vector machinery. */
+ /* Flags. Read-only for all callers. */
unsigned f; /* flags */
#define TVSF_SKIP 0x0001u /* skip this test group */
#define TVSF_OPEN 0x0002u /* test is open */
#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 */
- size_t regsz; /* size of register entry */
+ /* Test configuration. Read-only for all callers. */
+ struct tvec_config cfg; /* test configuration */
+
+ /* Registers. Available to execution environments, which may modify the
+ * contents of the active registers, as defined by the current test group,
+ * but not the vector pointers themselves or inactive registers.
+ */
struct tvec_reg *in, *out; /* register vectors */
- /* Test groups state. Available to output formatters. */
- const struct tvec_test *tests, *test; /* all tests and current test */
+ /* Test group state. Read-only for all callers. */
+ const struct tvec_test *test; /* current test */
/* Test scoreboard. Available to output formatters. */
unsigned curr[TVOUT_LIMIT], all[TVOUT_LIMIT], grps[TVOUT_LIMIT];
* @out@, and @i@ is an integer, then this evaluates to the address of the
* @i@th register in the selected vector.
*/
-#define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->regsz)
-
-struct tvec_config {
- /* An overall test configuration. */
-
- const struct tvec_test *tests; /* the tests to be performed */
- unsigned nrout, nreg; /* number of output/total regs */
- size_t regsz; /* size of a register */
-};
+#define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->cfg.regsz)
/*----- Output formatting -------------------------------------------------*/
const struct tvec_outops *ops; /* pointer to operations */
};
+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) */
+};
+
+#define TVEC_LEVELS(_) \
+ _(NOTE, "notice", 4) \
+ _(ERR, "ERROR", 8)
+enum {
+#define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
+ TVEC_LEVELS(TVEC_DEFLEVEL)
+#undef TVEC_DEFLEVEL
+ TVLEV_LIMIT
+};
+
/* Benchmarking details. */
enum {
TVBU_OP, /* counting operations of some kind */
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. */
/* Release any resources acquired by the driver. */
};
-#define TVEC_LEVELS(_) \
- _(NOTE, "notice", 4) \
- _(ERR, "ERROR", 8)
-
-enum {
-#define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
- TVEC_LEVELS(TVEC_DEFLEVEL)
-#undef TVEC_DEFLEVEL
- TVLEV_LIMIT
-};
-
/*----- Session lifecycle -------------------------------------------------*/
/* --- @tvec_begin@ --- *
*/
extern tvec_envsetupfn tvec_benchsetup;
-extern tvec_envsetfn tvec_benchset;
+extern tvec_envfindvarfn tvec_benchfindvar;
extern tvec_envbeforefn tvec_benchbefore;
extern tvec_envrunfn tvec_benchrun;
extern tvec_envafterfn tvec_benchafter;
#define TVEC_BENCHENV \
{ sizeof(struct tvec_benchctx), \
tvec_benchsetup, \
- tvec_benchset, \
+ tvec_benchfindvar, \
tvec_benchbefore, \
tvec_benchrun, \
tvec_benchafter, \
/*----- Remote execution --------------------------------------------------*/
+struct tvec_remoteenv;
+
struct tvec_remotecomms {
int infd, outfd; /* input and output descriptors */
dbuf bout; /* output buffer */
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 */
dstr prgwant, progress; /* progress: wanted/reported */
unsigned exwant, exit; /* exit status wanted/reported */
#define TVRF_RCNMASK 0x0300u /* reconnection behaviour: */
-#define TVRCN_SKIP 0x0000u /* skip unless connected */
-#define TVRCN_DEMAND 0x0100u /* connect on demand */
+#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' */
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$%.
+ */
struct tvec_remoteenv_slots {
tvec_connectfn *connect; /* connection function */
const struct tvec_env *env; /* subsidiary environment */
+ unsigned dflt_reconn; /* default reconnection */
};
struct tvec_remoteenv {
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_envsetfn tvec_remoteset;
+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_remoteset, \
- 0, \
+ 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: Reports the progress of a test execution to the client.
+ *
+ * The framework makes use of tokens beginning with %|%|%:
+ *
+ * * %|%IDLE|%: during the top-level server code;
+ *
+ * * %|%SETUP|%: during the enclosing environment's @before@
+ * function;
+ *
+ * * %|%RUN|%: during the environment's @run@ function, or the
+ * test function; and
+ *
+ * * %|%DONE|%: during the enclosing environment's @after@
+ * function.
+ *
+ * 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 PRINTF_LIKE(1, 2) int tvec_setprogress(const char */*status*/, ...);
extern int tvec_setprogress_v(const char */*status*/, va_list */*ap*/);
+/* --- @tvec_remoteserver@ --- *
+ *
+ * Arguments: @int infd@, @int outfd@ = input and output file descriptors
+ * @const struct tvec_config *config@ = test configuration
+ *
+ * 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@.
+ *
+ * This function is not particularly general purpose. It
+ * expects to `take over' the process, and makes use of private
+ * global variables.
+ */
+
extern int tvec_remoteserver(int /*infd*/, int /*outfd*/,
const struct tvec_config */*config*/);
struct tvec_timeoutenv {
struct tvec_env _env;
- unsigned timer;
- double t;
- const 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;
- unsigned timer;
- double t;
+ 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_SETMASK (TVTF_SETTMO) /* mask of @TVTF_SET...@ */
+#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_envsetfn tvec_timeoutset;
+extern tvec_envfindvarfn tvec_timeoutfindvar;
extern tvec_envbeforefn tvec_timeoutbefore;
extern tvec_envrunfn tvec_timeoutrun;
extern tvec_envafterfn tvec_timeoutafter;
#define TVEC_TIMEOUTENV \
{ sizeof(struct tvec_timeoutctx), \
tvec_timeoutsetup, \
- tvec_timeoutset, \
+ tvec_timeoutfindvar, \
tvec_timeoutbefore, \
tvec_timeoutrun, \
tvec_timeoutafter, \
* message.
*/
-extern const char *tvec_strlevel(unsigned /*level*/);
+extern const char *tvec_strlevel(unsigned /*level*/);
/* --- @tvec_report@, @tvec_report_v@ --- *
*
extern PRINTF_LIKE(2, 3)
void tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
+/* --- @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_humanoutput@ --- *
*
* Arguments: @FILE *fp@ = output file to write on
extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
const char */*expect*/, va_list */*ap*/);
-/* --- @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
*
* 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
*
* 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 PRINTF_LIKE(4, 5)
+extern PRINTF_LIKE(5, 6)
int tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
- const char */*delims*/, const char */*expect*/, ...);
+ 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 --------------------------------*/
#define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
(tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
+/*----- Size type ---------------------------------------------------------*/
+
+/* A size is an unsigned integer followed by an optional unit specifier
+ * consisting of an SI unit prefix and (optionally) the letter `B'.
+ */
+
+extern const struct tvec_regty tvty_size;
+
+/* --- @tvec_claimeq_size@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @unsigned long sz0, sz1@ = two sizes
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @sz0@ and @sz1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @u0@ and @u1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @u0@ is printed as the output
+ * value and @u1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_SIZE@ 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 @u0@ and @u1@ arguments in the failure message.
+ */
+
+int tvec_claimeq_size(struct tvec_state *tv,
+ unsigned long sz0, unsigned long sz1,
+ const char *file, unsigned lno, const char *expr);
+#define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
+ (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
+
/*----- 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.
double delta; /* maximum tolerable difference */
};
+extern const struct tvec_floatinfo tvflt_finite, tvflt_nonneg;
+
/* --- @tvec_claimeqish_float@, @TVEC_CLAIMEQISH_FLOAT@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @const char *file@, @unsigned @lno@ = calling file and line
* @const char *expr@ = the expression to quote on failure
*
- * Returns: Nonzero if @f0@ and @u1@ are sufficiently close, otherwise
+ * Returns: Nonzero if @f0@ and @f1@ are sufficiently close, otherwise
* zero.
*
* Use: Check that values of @f0@ and @f1@ are sufficiently close.
* %$y$% when %$|x - y| < \delta$%.
*
* * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches
- * %$y$% when %$|1 - y/x| < \delta$%. (Note that this
- * criterion is asymmetric FIXME
+ * %$y$% when %$|1 - x/y| < \delta$%. (Note that this
+ * criterion is asymmetric. Write %$x \approx_\delta y$%
+ * if and only if %$|1 - x/y < \delta$%. Then, for example,
+ * if %$y/(1 + \delta) < x < y (1 - \delta)$%, then
+ * %$x \approx_\delta y$%, but %$y \not\approx_\delta x$%.)
*
* The @TVEC_CLAIM_FLOAT@ macro is similar, only it (a)
* identifies the file and line number of the call site
const char */*file*/, unsigned /*lno*/,
const char */*expr*/);
#define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta) \
- (tvec_claimeqish_float(tv, f0, f1, f, delta, , __FILE__, __LINE__, \
+ (tvec_claimeqish_float(tv, f0, f1, f, delta, __FILE__, __LINE__, \
#f0 " /= " #f1 " (+/- " #delta ")"))
/* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- *
#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.
+ */
+
+extern const struct tvec_regty tvty_duration;
+
+/* --- @tvec_parsedurunit@ --- *
+ *
+ * Arguments: @double *scale_out@ = where to leave the scale
+ * @const char **p_inout@ = input unit string, updated
+ *
+ * Returns: Zero on success, %$-1$% on error.
+ *
+ * Use: If @*p_inout@ begins with a unit string followed by the end
+ * of the string or some non-alphanumeric character, then store
+ * the corresponding scale factor in @*scale_out@, advance
+ * @*p_inout@ past the unit string, and return zero. Otherwise,
+ * return %$-1$%.
+ */
+
+extern int tvec_parsedurunit(double */*scale_out*/,
+ const char **/*p_inout*/);
+
+/* --- @tvec_claimeqish_duration@, @TVEC_CLAIMEQISH_DURATION@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @double to, t1@ = two durations
+ * @unsigned f@ = flags (@TVFF_...@)
+ * @double delta@ = maximum tolerable difference
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @t0@ and @t1@ are sufficiently close, otherwise
+ * zero.
+ *
+ * Use: Check that values of @t0@ and @t1@ are sufficiently close.
+ * This is essentially the same as @tvec_claimeqish_float@, only
+ * it dumps the values as durations on a mismatch.
+ *
+ * The @TVEC_CLAIM_FLOAT@ 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 @t0@ and @t1@ arguments (and @delta@) in the failure
+ * message.
+ */
+
+extern int tvec_claimeqish_duration(struct tvec_state */*tv*/,
+ double /*t0*/, double /*t1*/,
+ unsigned /*f*/, double /*delta*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQISH_DURATION(tv, t0, t1, f, delta) \
+ (tvec_claimeqish_duration(tv, t0, t1, f, delta, __FILE__, __LINE__, \
+ #t0 " /= " #t1 " (+/- " #delta ")"))
+
+/* --- @tvec_claimeq_duration@, @TVEC_CLAIMEQ_DURATION@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @double t0, t1@ = two durations
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @t0@ and @t1@ are identical, otherwise zero.
+ *
+ * Use: Check that values of @t0@ and @t1@ are identical. The
+ * function is exactly equivalent to @tvec_claimeqish_duration@
+ * with @f == TVFF_EXACT@; the macro is similarly like
+ * @TVEC_CLAIMEQISH_DURATION@ with @f == TVFF_EXACT@, except
+ * that it doesn't bother to quote a delta.
+ */
+
+int tvec_claimeq_duration(struct tvec_state */*tv*/,
+ double /*t0*/, double /*t1*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQ_DURATION(tv, t0, t1) \
+ (tvec_claimeq_float(tv, t0, t1, __FILE__, __LINE__, #t0 " /= " #t1))
/*----- Enumerated types --------------------------------------------------*/
* 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).
*/
* 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_alloctext@, @tvec_allocbytes@ --- *
+ *
+ * Arguments: @union tvec_regval *rv@ = register value
+ * @size_t sz@ = required size
+ *
+ * Returns: ---
+ *
+ * Use: Allocated space in a text or binary string register. If the
+ * current register size is sufficient, its buffer is left
+ * alone; otherwise, the old buffer, if any, is freed and a
+ * fresh buffer allocated. These functions are not intended to
+ * be used to adjust a buffer repeatedly, e.g., while building
+ * output incrementally: (a) they will perform badly, and (b)
+ * the old buffer contents are simply discarded if reallocation
+ * is necessary. Instead, use a @dbuf@ or @dstr@.
+ *
+ * The @tvec_alloctext@ function sneakily allocates an extra
+ * byte for a terminating zero. The @tvec_allocbytes@ function
+ * doesn't do this.
+ */
+
+extern void tvec_alloctext(union tvec_regval */*rv*/, size_t /*sz*/);
+extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
-/* --- @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@ --- *
+/*----- Buffer type -------------------------------------------------------*/
+
+/* Buffer registers are primarily used for benchmarking. Only a buffer's
+ * allocation parameters are significant: its contents are ignored on
+ * comparison and output, and unspecified on input.
*
- * Arguments: @union tvec_regval *rv@ = register value
- * @size_t sz@ = required size
+ * 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.
*
- * Returns: ---
+ * Units other than `B' are used on output only when the size would be
+ * expressed exactly.
*
- * Use: Allocated space in a text or binary string register. If the
- * current register size is sufficient, its buffer is left
- * alone; otherwise, the old buffer, if any, is freed and a
- * fresh buffer allocated. These functions are not intended to
- * be used to adjust a buffer repeatedly, e.g., while building
- * output incrementally: (a) they will perform badly, and (b)
- * the old buffer contents are simply discarded if reallocation
- * is necessary. Instead, use a @dbuf@ or @dstr@.
+ * Buffers are %%\emph{not}%% allocated by default. In benchmarks, this is
+ * best done in a @before@ function.
*
- * The @tvec_allocstring@ function sneakily allocates an extra
- * byte for a terminating zero. The @tvec_allocbytes@ function
- * doesn't do this.
+ * No @claimeq@ functions or macros are provided for buffers because they
+ * don't seem very useful.
*/
-extern void tvec_allocstring(union tvec_regval */*rv*/, size_t /*sz*/);
-extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
+extern const struct tvec_regty tvty_buffer;
-/*----- Buffer type -------------------------------------------------------*/
+/* --- @tvec_initbuffer@ --- *
+ *
+ * Arguments: @union tvec_regval *rv@ = register value
+ * @const union tvec_regval *ref@ = reference buffer
+ * @size_t sz@ = size to allocate
+ *
+ * Returns: ---
+ *
+ * Use: Initialize the alignment parameters in @rv@ to match @ref@,
+ * and the size to @sz@.
+ */
-/* 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.
+extern void tvec_initbuffer(union tvec_regval */*rv*/,
+ const union tvec_regval */*ref*/, size_t /*sz*/);
+
+/* --- @tvec_allocbuffer@ --- *
+ *
+ * Arguments: @union tvec_regval *rv@ = register value
+ *
+ * Returns: ---
*
- * 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.
+ * Use: Allocate @sz@ bytes to the buffer and fill the space with a
+ * distinctive pattern.
*/
-extern const struct tvec_regty tvty_buffer;
+extern void tvec_allocbuffer(union tvec_regval */*rv*/);
/*----- That's all, folks -------------------------------------------------*/
~mdw / mLib / blobdiff