@@@ remote works?

[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 ------------------------------------------------------*/

#ifndef MLIB_BITS_H
#  include "bits.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 */
  kludge64 s; uint32 ns;		/* real time, seconds and nanos */
  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 (*now)(struct bench_timer */*bt*/, struct bench_time */*t_out*/);
    /* Fill in @*t_out@ with the current time. v*/

  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_...@) */
  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:	---
 *
 * Returns:	A freshly constructed standard timer object.
 *
 * Use:		Allocate a timer.  Dispose of it by calling
 *		@tm->ops->destroy(tm)@ when you're done.
 */

extern struct bench_timer *bench_createtimer(void);

/* --- @bench_init@ --- *
 *
 * Arguments:	@struct bench_state *b@ = bench state to initialize
 *		@struct bench_timer *tm@ = timer to attach
 *
 * Returns:	---
 *
 * 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@.
 */

extern void 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_timing *t_out@ = where to leave the timing
 *		@struct bench_state *b@ = benchmark state
 *		@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_timing */*t_out*/,
			 struct bench_state */*b*/,
			 double /*base*/, bench_fn */*fn*/, void */*ctx*/);

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

#ifdef __cplusplus
  }
#endif

#endif