@@@ mostly bench docs

[mLib] / test / bench.h

/* -*-c-*-
 *
 * Benchmarking support
 *
 * (c) 2023 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Library General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * mLib is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
 * License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with mLib.  If not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 * USA.
 */

#ifndef MLIB_BENCH_H
#define MLIB_BENCH_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <limits.h>
#include <time.h>

#ifndef MLIB_BITS_H
#  include "bits.h"
#endif

#ifndef MLIB_CONTROL_H
#  include "control.h"
#endif

#ifndef MLIB_DSTR_H
#  include "dstr.h"
#endif

#ifndef MLIB_MACROS_H
#  include "macros.h"
#endif

#ifndef MLIB_GPRINTF_H
#  include "gprintf.h"
#endif

/*----- Timers ------------------------------------------------------------*/

struct bench_time {
  unsigned f;				/* flags */
#define BTF_TIMEOK 1u			/*   @s@ ad @ns@ slots are value */
#define BTF_CYOK 2u			/*   @cy@ slot is valid */
#define BTF_ANY (BTF_TIMEOK | BTF_CYOK)	/*   some part is useful */
  union {
    struct { kludge64 s; uint32 ns; } ts; /* @struct timespec@-ish */
    clock_t clk;			/* @clock@ */
    kludge64 rawns;			/* raw nanosecond count */
  } t;					/* time */
  kludge64 cy;				/* count of CPU cycles */
};

struct bench_timing {
  unsigned f;				/* flags (@BTF_...@) */
  double n, t, cy;			/* count, time, and cycles */
};

struct bench_timer {
  const struct bench_timerops *ops;
  unsigned ref;
};

struct bench_timerops {
  void (*describe)(struct bench_timer */*bt*/, dstr */*d*/);
    /* Write a description of the timer to @d@. */

  int (*preflight)(struct bench_timer */*bt*/);
    /* Return zero if timer is ready to go, or %$-1$% otherwise.  The @now@
     * function will only be called following a successful @preflight@ on the
     * same thread.
     */

  int (*now)(struct bench_timer */*bt*/, struct bench_time */*t_out*/,
	      unsigned /*f*/);
#define BTF_T0 0u			/* fetching first time of a pair */
#define BTF_T1 1u			/* fetching second time of a pair */
    /* Fill in @*t_out@ with the current time.  Return zero on success
     * %%\emph{or} permanent failure; return %$-1$% on temporary failure.
     */

  void (*diff)(struct bench_timer */*bt*/,
	       struct bench_timing */*delta_out*/,
	       const struct bench_time */*t0*/,
	       const struct bench_time */*t1*/);
    /* Subtract the time @t0@ from the time @t1@, leaving the result in
     * @*delta_out@, setting flags as appropriate.
     */

  void (*destroy)(struct bench_timer */*bt*/);
    /* Release the timer and any resources it holds. */
};

/* --- @bench_createtimer@ --- *
 *
 * Arguments:	@const char *config@ = user-supplied configuration string
 *
 * 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(const char *config);

/* --- @BENCH_TIMELOOP_DECLS@ --- *
 *
 * Arguments:	---
 *
 * Use:		Expands to the declarations needed by @BENCH_TIMELOOP_TAG@.
 *		These should be at block scope, not at toplevel.
 */

#define BENCH_TIMELOOP_DECLS						\
  struct bench_timer *_bench_tm;					\
  struct bench_time _bench_t0, _bench_t1;				\
  unsigned long _bench_n, _bench_n1

/* --- @BENCH_TIMELOOP_TAG@ --- *
 *
 * Arguments:	@tag@ = control structure tag
 *		@struct bench_state *tm@ = benchmark timer
 *		@struct bench_timing *delta_out@ = where to put the result
 *		@double n@ = number of iterations
 *
 * Returns:	---
 *
 * Use:		@BENCH_TIMELOOP_TAG(tag, tm, delta_out, n) stmt@ runs @stmt@
 *		@n@ times, capturing the time and/or CPU cycles taken in
 *		@*delta_out@.  The iteration count must be no more than the
 *		%%\emph{square}%% of @ULONG_MAX@.  If @stmt@ executes a free
 *		@break@ statement, then the containing loop -- which must
 *		exist -- is exited.
 *
 *		This macro is not intended to be used directly by users: it
 *		is used internally by @bench_calibrate@ and @BENCH_MEASURE@.
 */

#define BENCH_TIMELOOP_TAG(tag, tm, delta_out, n, onbreak)		\
  MC_BEFORE(tag##__benchtl_setup, {					\
    double _R = ULONG_MAX; double _n = (n);				\
									\
    _bench_tm = (tm);							\
    if (_n <= _R) { _bench_n1 = 0; _bench_n = _n; }			\
    else { _bench_n1 = _n/_R; _bench_n = _n - _R*_bench_n1; }		\
  })									\
  MC_TARGET(tag##__benchtl_break, { break; })				\
  MC_AFTER(tag##__benchtl_end, {					\
    _bench_tm->ops->diff(_bench_tm, (delta_out), &_bench_t0, &_bench_t1); \
  })									\
  MC_DOWHILE(tag##__benchtl_countdown, _bench_n1--)			\
    MC_AFTER(tag##__benchtl_post, { _bench_n = ULONG_MAX; })		\
    MC_DOWHILE(tag##__benchtl_t1,					\
	       _bench_tm->ops->now(_bench_tm, &_bench_t1, BTF_T1))	\
      MC_WRAP(tag##__benchtl_t0,					\
	{ while (_bench_tm->ops->now(_bench_tm, &_bench_t0, BTF_T0)) ; }, \
	{ ; },								\
	{ MC_GOTARGET(tag##__benchtl_break); })

/*----- Measuring ---------------------------------------------------------*/

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 */
};

typedef void bench_fn(unsigned long /*n*/, void */*ctx*/);
  /* Run the benchmark @n@ times, given a context pointer @ctx@. */

/* --- @bench_init@ --- *
 *
 * Arguments:	@struct bench_state *b@ = bench state to initialize
 *		@struct bench_timer *tm@ = timer to attach, or null
 *
 * 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@.
 *
 *		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 int bench_init(struct bench_state */*b*/, struct bench_timer */*tm*/);

/* --- @bench_destroy@ --- *
 *
 * Arguments:	@struct bench_state *b@ = bench state
 *
 * Returns:	---
 *
 * Use:		Destroy the benchmark state, releasing the resources that it
 *		holds.
 */

extern void bench_destroy(struct bench_state */*b*/);

/* --- @bench_calibrate@ --- *
 *
 * Arguments:	@struct bench_state *b@ = bench state
 *		@unsigned f@ = calibration flags
 *
 * Returns:	Zero on success, %$-1$% if calibration failed.
 *
 * Use:		Calibrate the benchmark state, so that it can be used to
 *		measure performance reasonably accurately.
 *
 *		Calibration will take into account how the subject code is
 *		going to be located.  If you're going to use @BENCH_MEASURE@
 *		to measure a piece of literal code, then leave @f@ zero.  If
 *		the code to be measured is going to be executed via an
 *		indirect branch, e.g., through the @measure@ function, then
 *		set @BTF_INDIRECT@.
 */

#define BTF_INDIRECT 1u
extern int bench_calibrate(struct bench_state */*b*/, unsigned /*f*/);

/* --- @bench_preflight@ --- *
 *
 * Arguments:	@struct bench_state *b@ = benchmark state
 *
 * Returns:	Zero on success, %$-1$% on failure.
 *
 * Use:		Prepares for benchmarking on the current thread.  Current
 *		checks are that the timer is calibrated and that it can
 *		successfully measure time; the timer preflight is also run.
 *
 *		Users are unlikely to find this function useful: it's called
 *		automatically by the @BENCH_MEASURE@ macro and the
 *		@bench_measure@ function.
 */

extern int bench_preflight(struct bench_state */*b*/);

/* --- @bench_adapt@ --- *
 *
 * Arguments:	@double *n_inout@ = number of iterations, updated
 *		@double target_s@ = target time in seconds
 *		@const struct bench_timing *t@ = timing from the previous run
 *
 * Returns:	Nonzero if the measurement is sufficient; zero to run again.
 *
 * Use:		This function determines a suitable number of iterations of a
 *		benchmark function to perform next.  It is used in a loop
 *		such as the following.
 *
 *			@BENCH_TIMELOOP_DECLS;@
 *			@struct bench_timer *tm;@
 *			@struct bench_timing t;@
 *			@double n = 1.0, target_s = 1.0;@
 *
 *			@do {@
 *			  @BENCH_TIMELOOP_TAG(time, tm, &t, n, { break; })@
 *			    (do @_bench_n@ iterations of some computation)@;@
 *			@} while (!bench_adapt(&n, target_s, &t));@
 *
 *		On entry, @*n_inout@ should be the number of iterations
 *		performed by the previous pass, and @*t@ the resulting time;
 *		the @BTF_TIMEOK@ flag must be set in @t->f@.  If the timing
 *		is sufficient -- @t->t@ is sufficiently close to @target_s@
 *		-- then the function returns nonzero to indicate that
 *		measurement is complete.  Otherwise, it sets @*n_inout@ to a
 *		new, larger iteration count and returns zero to indicate that
 *		a further pass is necessary.
 *
 *		Users are unlikely to find this function useful: it's called
 *		automatically by the @BENCH_MEASURE@ macro and the
 *		@bench_measure@ function.
 */

extern int bench_adapt(double */*n_inout*/, double /*target_s*/,
		       const struct bench_timing */*t*/);

/* --- @bench_adjust@ --- *
 *
 * Arguments:	@struct bench_state *b@ = benchmark state
 *		@struct bench_timing *t_inout@ = timing to adjust
 *		@double n@ = number of external iterations performed
 *		@double base@ = number of internal operations per external
 *			iteration
 *
 * Returns:	---
 *
 * Use:		Adjusts a raw timing, as captured by @BENCH_TIMELOOP_TAG@,
 *		according to the calibration data captured in @b@.
 *		On exit, the timing data is updated, and @t->n@ is set to the
 *		product @n*base@.
 *
 *		Users are unlikely to find this function useful: it's called
 *		automatically by the @BENCH_MEASURE@ macro and the
 *		@bench_measure@ function.
 */

extern void bench_adjust(struct bench_state */*b*/,
			 struct bench_timing */*t_inout*/,
			 double /*n*/, double /*base*/);

/* --- @BENCH_MEASURE_DECLS@ --- *
 *
 * Arguments:	---
 *
 * Use:		Expands to the declarations needed by @BENCH_MEASURE@.
 *		These should be at block scope, not at toplevel.
 */

#define BENCH_MEASURE_DECLS						\
  struct bench_state *_bench_b;						\
  struct bench_timing *_bench_t;					\
  double _bench_nn;							\
  BENCH_TIMELOOP_DECLS

/* --- @BENCH_MEASURE@, @BENCH_MEASURE_TAG@ --- *
 *
 * Arguments:	@tag@ = control structure tag
 *		@struct bench_state *b@ = benchmark state
 *		@int &rc@ = where to put the result code (zero on success,
 *			%$-1$% on failure)
 *		@struct bench_timing *t_out@ = where to put the result
 *		@double base@ = number of operations per external iteration
 *
 * Returns:	---
 *
 * Use:		@BENCH_MEASURE(b, rc, delta_out, n) stmt@ measures the
 *		execution of @stmt@.
 *
 *		The statement should perform @_bench_n@ iterations of some
 *		operation.  It will be invoked multiple times, with varying
 *		iteration counts, so as to run for approximately
 *		@b->target_s@ seconds.
 *
 *		On success, the resulting timing is left in @*t_out@, with
 *		@t_out->n@ holding the product of the final iteration count
 *		and @base@, and @rc@ is set to zero.  If the timer fails, or
 *		if @stmt@ invokes a free @break@ statement, then @rc@ is set
 *		to %$-1$%.
 *
 *		The macro @BENCH_MEASURE_TAG@ is the same, except that it
 *		allows an explicit control-structure tag to be set so that it
 *		can be used within larger control structure macros.
 */

#define BENCH_MEASURE_TAG(tag, b, rc, t_out, base)			\
  MC_BEFORE(tag##__benchmsr_setup, {					\
    _bench_b = (b); _bench_t = (t_out); _bench_nn = 1.0;		\
    if (bench_preflight(_bench_b)) MC_GOTARGET(tag##__benchmsr_fail);	\
  })									\
  MC_TARGET(tag##__benchmsr_done,					\
    { bench_adjust(_bench_b, _bench_t, _bench_nn, (base)); (rc) = 0; }) \
  MC_TARGET(tag##__benchmsr_fail, { (rc) = -1; })			\
  for (;;)								\
    MC_WRAP(tag##__benchmsr_loop,					\
      { ; },								\
      { _bench_t->f &= _bench_b->f;					\
	if (!(_bench_t->f&BTF_TIMEOK)) MC_GOTARGET(tag##__benchmsr_fail); \
	if (bench_adapt(&_bench_nn, _bench_b->target_s, _bench_t))	\
	  MC_GOTARGET(tag##__benchmsr_done);				\
      },								\
      { MC_GOTARGET(tag##__benchmsr_fail); })				\
    BENCH_TIMELOOP_TAG(tag##__benchmsr_time,				\
		       _bench_b->tm, _bench_t, _bench_nn, { break; })

#define BENCH_MEASURE(b, rc, t_out, base)				\
  BENCH_MEASURE_TAG(bench_measure, b, rc, t_out, base)

/* --- @bench_measure@ --- *
 *
 * Arguments:	@struct bench_state *b@ = benchmark state
 *		@struct bench_timing *t_out@ = where to leave the timing
 *		@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.
 *
 * Use:		Measure a function.  The function @fn@ is called adaptively
 *		with an iteration count @n@ set so as to run for
 *		approximately @b->target_s@ seconds.
 *
 *		The result is left in @*t_out@, with @t_out->n@ counting the
 *		final product of the iteration count and @base@ (which might,
 *		e.g., reflect the number of inner iterations the function
 *		performs, or the number of bytes it processes per iteration).
 */

extern int bench_measure(struct bench_state */*b*/,
			 struct bench_timing */*t_out*/,
			 double /*base*/, bench_fn */*fn*/, void */*ctx*/);

/*----- Reporting ---------------------------------------------------------*/

enum {
  BTU_OP,			       /* counting operations of some kind */
  BTU_BYTE,				/* counting bytes (@rbuf >= 0@) */
  BTU_LIMIT				/* (number of units) */
};

/* --- @bench_report@ --- *
 *
 * Arguments:	@const struct gprintf_ops *gops, void *gp@ = output formatter
 *		@unsigned unit@ = unit processed by the benchmark function
 *		@const struct bench_timing *t@ = benchmark result
 *
 * Returns:	---
 *
 * Use:		Format, to the output identified by @gops@ and @go@, a
 *		human-readable report of the benchmarking result @t@.  No
 *		newline is appended.
 *
 *		The output format is subject to change in later versions.
 */

extern void bench_report(const struct gprintf_ops */*gops*/, void */*go*/,
			 unsigned /*unit*/,
			 const struct bench_timing */*t*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif