@@@ misc mess

[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 <time.h>

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

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

/*----- Data structures ---------------------------------------------------*/

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

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

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

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@. */

/*----- Functions provided ------------------------------------------------*/

/* --- @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_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
 *
 * Returns:	Zero on success, %$-1$% if calibration failed.
 *
 * Use:		Calibrate the benchmark state, so that it can be used to
 *		measure performance reasonably accurately.
 */

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

/* --- @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*/);

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

#ifdef __cplusplus
  }
#endif

#endif