@@@ man wip

[mLib] / test / tvec.h

diff --git a/test/tvec.h b/test/tvec.h
index 1e1e154..b2ae674 100644 (file)
--- a/test/tvec.h
+++ b/test/tvec.h
@@ -194,6 +194,11 @@ union tvec_regval {
   double f;                            /* floating point */
   struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
   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
@@ -514,7 +519,7 @@ enum {
   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. */
@@ -1727,6 +1732,7 @@ extern int tvec_nexttoken(struct tvec_state */*tv*/);
  *
  * 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
  *
@@ -1749,14 +1755,23 @@ extern int tvec_nexttoken(struct tvec_state */*tv*/);
  *             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 --------------------------------*/
 
@@ -2419,13 +2434,24 @@ 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.
  *
- * 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.
+ * 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.
  *
  * No @claimeq@ functions or macros are provided for buffers because they
  * don't seem very useful.
@@ -2433,6 +2459,33 @@ extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
 
 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