X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/0335afec2c33fefcd6d3cb2c39d014ab2519b2c2..13ee740655965453b2f3fcd7093d2d8b13839903:/test/bench.h

diff --git a/test/bench.h b/test/bench.h
index c0627e2..bca3b01 100644
--- a/test/bench.h
+++ b/test/bench.h
@@ -38,6 +38,10 @@
 #  include "bits.h"
 #endif
 
+#ifndef MLIB_DSTR_H
+#  include "dstr.h"
+#endif
+
 /*----- Data structures ---------------------------------------------------*/
 
 struct bench_time {
@@ -57,6 +61,9 @@ struct bench_timing {
 struct bench_timer { const struct bench_timerops *ops; };
 
 struct bench_timerops {
+  void (*describe)(struct bench_timer */*bt*/, dstr */*d*/);
+    /* Write a description of the timer to @d@. */
+
   void (*now)(struct bench_timer */*bt*/, struct bench_time */*t_out*/);
     /* Fill in @*t_out@ with the current time. v*/
 
@@ -68,6 +75,7 @@ struct bench_state {
   struct bench_timer *tm;		/* a timer */
   double target_s;			/* target time to run benchmarks */
   unsigned f;				/* calibration flags (@BTF_...@) */
+#define BTF_CLB 0x0100			/*   tried calibrating */
   struct { double m, c; } clk, cy;	/* calculated overheads */
 };
 
@@ -78,32 +86,41 @@ typedef void bench_fn(unsigned long /*n*/, void */*ctx*/);
 
 /* --- @bench_createtimer@ --- *
  *
- * Arguments:	---
+ * Arguments:	@const char *config@ = user-supplied configuration string
  *
- * Returns:	A freshly constructed standard timer object.
+ * Returns:	A freshly constructed standard timer object, or null on
+ *		failure.
  *
  * Use:		Allocate a timer.  Dispose of it by calling
  *		@tm->ops->destroy(tm)@ when you're done.
+ *
+ *		Applications should not set configuration strings except as
+ *		established by user action, e.g., from a command-line option,
+ *		environment variable, or configuration file.
  */
 
-extern struct bench_timer *bench_createtimer(void);
+extern struct bench_timer *bench_createtimer(const char *config);
 
 /* --- @bench_init@ --- *
  *
  * Arguments:	@struct bench_state *b@ = bench state to initialize
- *		@struct bench_timer *tm@ = timer to attach
+ *		@struct bench_timer *tm@ = timer to attach, or null
  *
- * Returns:	---
+ * Returns:	Zero on success, %$-1$% on failure.
+ *
+ * Use:		Initialize the benchmark state.  On success, the timer state
+ *		still needs to be calibrated (use @bench_calibrate@) before
+ *		it can be used, but this will be done automatically by
+ *		@bench_measure@ if it's not done by hand earlier.  The timer
+ *		is now owned by the benchmark state and will be destroyed by
+ *		@bench_destroy@.
  *
- * Use:		Initialize the benchmark state.  It still needs to be
- *		calibrated (use @bench_calibrate@) before it can be used, but
- *		this will be done automatically by @bench_measure@ if it's
- *		not done by hand earlier.  The timer is now owned by the
- *		benchmark state and will be destroyed by @bench_destroy@.
+ *		The only reason for failure is if @tm@ was null on entry,
+ *		and automatic construction of a timer failed.  The state is
+ *		safe to discard, but calling @bench_destroy@ is safe too.
  */
 
-extern void bench_init(struct bench_state */*b*/,
-		       struct bench_timer */*tm*/);
+extern int bench_init(struct bench_state */*b*/, struct bench_timer */*tm*/);
 
 /* --- @bench_destroy@ --- *
  *
@@ -121,7 +138,7 @@ extern void bench_destroy(struct bench_state */*b*/);
  *
  * Arguments:	@struct bench_state *b@ = bench state
  *
- * Returns:	Zero on success, @-1@ if calibration failed.
+ * Returns:	Zero on success, %$-1$% if calibration failed.
  *
  * Use:		Calibrate the benchmark state, so that it can be used to
  *		measure performance reasonably accurately.
@@ -136,7 +153,7 @@ extern int bench_calibrate(struct bench_state */*b*/);
  *		@double base@ = number of internal units per call
  *		@bench_fn *fn@, @void *ctx@ = benchmark function to run
  *
- * Returns:	Zero on success, @-1@ if timing failed.
+ * Returns:	Zero on success, %$-1$% if timing failed.
  *
  * Use:		Measure a function.  The function @fn@ is called adaptively
  *		with an iteration count @n@ set so as to run for