@@@ fltfmt mess

[mLib] / test / tvec-bench.c

/* -*-c-*-
 *
 * Benchmarking in the test-vector framework
 *
 * (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.
 */

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

#include "bench.h"

#include "tvec.h"
#include "tvec-bench.h"
#include "tvec-output.h"
#include "tvec-types.h"

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

struct benchrun {
  struct tvec_state *tv;		/* test vector state */
  const struct tvec_env *env;		/* subordinate environment */
  void *ctx;				/* subordinate env's context */
  unsigned long *n;			/* iteration count address */
  const struct tvec_reg *in; struct tvec_reg *out; /* register vectors */
  tvec_testfn *fn;			/* test function to run */
};

/*----- Global variables --------------------------------------------------*/

struct bench_state *tvec_benchstate;	/* common benchmarking state */

/*----- Output utilities --------------------------------------------------*/

/* --- @tvec_benchreport@ --- *
 *
 * Arguments:	@const struct gprintf_ops *gops@ = print operations
 *		@void *go@ = print destination
 *		@unsigned unit@ = the unit being measured (@TVBU_...@)
 *		@unsigned style@ = output style (@TVSF_...@)
 *		@const struct bench_timing *t@ = the benchmark result
 *
 * Returns:	---
 *
 * Use:		Formats a report about the benchmark performance.  This
 *		function is intended to be called on by an output
 *		@ebench@ function.
 */

void tvec_benchreport(const struct gprintf_ops *gops, void *go,
		      unsigned unit, unsigned style,
		      const struct bench_timing *t)
{
  if (!t) {
    if (style&TVSF_RAW) gprintf(gops, go, "FAILED");
    else gprintf(gops, go, "benchmark FAILED");
  } else if (!(style&TVSF_RAW))
    bench_report(gops, go, unit, t);
  else {
    switch (unit) {
      case BTU_OP: gprintf(gops, go, "ops=%.0f", t->n); break;
      case BTU_BYTE: gprintf(gops, go, "bytes=%.0f", t->n); break;
      default: assert(0);
    }
    gprintf(gops, go, " sec=%.6g", t->t);
    if (t->f&BTF_CYOK) gprintf(gops, go, " cy=%.0f", t->cy);
  }
}

/*----- Default output implementation -------------------------------------*/

/* --- @fallback_bbench@ --- *
 *
 * Arguments:	@struct tvec_output *o@ = output sink, secretly a
 *			 @struct fallback_output@
 *		@const char *desc@ = adhoc test description
 *		@unsigned unit@ = measurement unit (@TVBU_...@)
 *
 * Returns:	---
 *
 * Use:		Report that a benchmark has started.
 *
 *		The fallback implementation does nothing here.  All of the
 *		reporting happens in @fallback_ebench@.
 */

static void fallback_bbench(struct tvec_output *o,
			    const char *desc, unsigned unit)
  { ; }

/* --- @fallback_ebench@ --- *
 *
 * Arguments:	@struct tvec_output *o@ = output sink, secretly a
 *			 @struct fallback_output@
 *		@const char *desc@ = adhoc test description
 *		@unsigned unit@ = measurement unit (@BTU_...@)
 *		@const struct bench_timing *t@ = measurement
 *
 * Returns:	---
 *
 * Use:		Report a benchmark's results
 *
 *		The fallback implementation just delegates to the default
 *		benchmark reporting to produce a line written through the
 *		standard @report@ output operation.
 */

static void fallback_ebench(struct tvec_output *o,
			    const char *desc, unsigned unit,
			    const struct bench_timing *t)
{
  struct tvec_fallbackoutput *fo = (struct tvec_fallbackoutput *)o;
  struct tvec_state *tv = fo->tv;
  const struct tvec_regdef *rd;
  dstr d = DSTR_INIT;
  unsigned f = 0;
#define f_any 1u

  /* Build the identification string. */
  dstr_putf(&d, "%s ", tv->test->name);
  if (desc)
    DPUTS(&d, desc);
  else
    for (rd = tv->test->regs; rd->name; rd++)
      if (rd->f&TVRF_ID) {
	if (f&f_any) DPUTS(&d, ", ");
	else f |= f_any;
	dstr_putf(&d, "%s = ", rd->name);
	rd->ty->dump(&TVEC_REG(tv, in, rd->i)->v, rd, TVSF_COMPACT,
		     &dstr_printops, &d);
      }
  DPUTS(&d, ": ");

  /* Report the benchmark results. */
  tvec_benchreport(&dstr_printops, &d, unit, 0, t);
  DPUTZ(&d);

  /* Write the result. */
  tvec_info(tv, "%s", d.buf);
  DDESTROY(&d);

#undef f_any
}

const struct tvec_benchoutops tvec_benchoutputfallback =
  { fallback_bbench, fallback_ebench };

/*----- Benchmark environment scaffolding ---------------------------------*/

/* --- @tvec_benchprep@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@struct bench_state **bst_inout@ = benchmark state (updated)
 *		@unsigned f@ = calibration flags
 *
 * Returns:	Zero on success, %$-1$% on failure.
 *
 * Use:		If @*bst_inout@ is null then allocate and initialize a fresh
 *		benchmark state with a default timer, and @*bst_inout@ is
 *		updated to point to the fresh state.  The storage for the
 *		state was allocated using the test vector state's arena.
 *
 *		If the benchmark state hasn't been calibrated, then this is
 *		done, passing @f@ to @bench_calibrate@.
 *
 *		On failure, the test group is skipped, reporting a suitable
 *		message, and %$-1$% is returned.  If a fresh benchmark state
 *		was allocated, but calibration failed, the state is
 *		%%\emph{not}%% released.
 */

int tvec_benchprep(struct tvec_state *tv,
		   struct bench_state **bst_inout, unsigned f)
{
  dstr d = DSTR_INIT;
  struct bench_timer *bt;
  struct bench_state *b;
  int rc;

  /* Set up the benchmarking state if it hasn't been done before. */
  if (*bst_inout)
    b = *bst_inout;
  else {
    bt = bench_createtimer(0);
      if (!bt)
	{ tvec_skipgroup(tv, "failed to create timer"); goto timer_failed; }
    X_NEW(b, tv->a); bench_init(b, bt); *bst_inout = b;
  }

  /* If the timer isn't calibrated yet then do that now. */
  if (!(b->f&BTF_CLB)) {
    b->tm->ops->describe(b->tm, &d);
    tvec_notice(tv, "calibrating timer `%s'...", d.buf);
    if (bench_calibrate(b, f))
      { tvec_skipgroup(tv, "failed to calibrate timer"); goto timer_failed; }
  } else if (!(b->f&BTF_ANY))
    { tvec_skipgroup(tv, "timer broken"); goto timer_failed; }

  rc = 0; goto end;

timer_failed:
  /* Give a `helpful' hint if the timer didn't work. */
  if (!getenv("MLIB_BENCH_DEBUG"))
    tvec_notice(tv, "set `MLIB_BENCH_DEBUG=t' in the environment "
		"for more detail");
  rc = -1;
  goto end;

end:
  dstr_destroy(&d);
  return (rc);
}

/* --- @tvec_benchsetup@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@const struct tvec_env *env@ = environment description
 *		@void *pctx@ = parent context (ignored)
 *		@void *ctx@ = context pointer to initialize
 *
 * Returns:	---
 *
 * Use:		Initialize a benchmarking environment context.
 *
 *		The environment description must really be a @struct
 *		tvec_benchenv@.  If the @bst@ slot is null, then a temporary
 *		benchmark state is allocated for the current test group and
 *		released at the end.  Otherwise, it must be the address of a
 *		pointer to a benchmark state: if the pointer is null, then a
 *		fresh state is allocated and initialized and the pointer is
 *		updated; otherwise, the pointer is assumed to refer to an
 *		existing valid benchmark state.
 */

void tvec_benchsetup(struct tvec_state *tv, const struct tvec_env *env,
		     void *pctx, void *ctx)
{
  struct tvec_benchctx *bc = ctx;
  const struct tvec_benchenv *be = (const struct tvec_benchenv *)env;
  const struct tvec_env *subenv = be->env;

  bc->be = be; bc->bst = 0; bc->subctx = 0;
  if (!tvec_benchprep(tv, be->bst, BTF_INDIRECT))
    { bc->bst = *be->bst; bc->dflt_target = bc->bst->target_s; }
  if (subenv && subenv->ctxsz) bc->subctx = x_alloc(tv->a, subenv->ctxsz);
  if (subenv && subenv->setup) subenv->setup(tv, subenv, bc, bc->subctx);
}

/* --- @tvec_benchfindvar@, @setvar@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@const char *var@ = variable name to set
 *		@const union tvec_regval *rv@ = register value
 *		@void **ctx_out@ = where to put the @setvar@ context
 *		@void *ctx@ = context pointer
 *
 * Returns:	@tvec_benchfindvar@ returns a pointer to the variable
 *		definition, or null; @setvar@ returns zero on success or
 *		%$-1$% on error.
 *
 * Use:		Find a definition for a special variable.  The following
 *		special variables are supported.
 *
 *		  * %|@target|% is the (approximate) duration to run
 *		    the benchmark.
 *
 *		Unrecognized variables are passed to the subordinate
 *		environment, if there is one.
 */

static int setvar(struct tvec_state *tv, const char *var,
		  const union tvec_regval *rv, void *ctx)
{
  struct tvec_benchctx *bc = ctx;

  if (STRCMP(var, ==, "@target")) {
    if (bc->f&TVBF_SETTRG) return (tvec_dupregerr(tv, var));
    bc->bst->target_s = rv->f; bc->f |= TVBF_SETTRG;
  } else assert("unknown var");
  return (0);
}

static const struct tvec_vardef target_var =
  { sizeof(struct tvec_reg), setvar, { "@target", &tvty_duration, -1, 0 } };

const struct tvec_vardef *tvec_benchfindvar
  (struct tvec_state *tv, const char *var, void **ctx_out, void *ctx)
{
  struct tvec_benchctx *bc = ctx;
  const struct tvec_benchenv *be = bc->be;
  const struct tvec_env *subenv = be->env;

  if (STRCMP(var, ==, "@target")) { *ctx_out = bc; return (&target_var); }
  else if (subenv && subenv->findvar)
    return (subenv->findvar(tv, var, ctx_out, bc->subctx));
  else return (0);
}

/* --- @tvec_benchbefore@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@void *ctx@ = context pointer
 *
 * Returns:	---
 *
 * Use:		Invoke the subordinate environment's @before@ function to
 *		prepare for the benchmark.
 */

void tvec_benchbefore(struct tvec_state *tv, void *ctx)
{
  struct tvec_benchctx *bc = ctx;
  const struct tvec_benchenv *be = bc->be;
  const struct tvec_env *subenv = be->env;

  if (subenv && subenv->before) subenv->before(tv, bc->subctx);
}

/* --- @tvec_benchrun@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@tvec_testfn *fn@ = test function to run
 *		@void *ctx@ = context pointer for the test function
 *
 * Returns:	---
 *
 * Use:		Measures and reports the performance of a test function.
 */

void tvec_benchrun(struct tvec_state *tv, tvec_testfn *fn, void *ctx)
{
  struct tvec_benchctx *bc = ctx;
  const struct tvec_benchenv *be = bc->be;
  const struct tvec_env *subenv = be->env;
  struct tvec_output *o = tv->output;
  struct tvec_fallbackoutput fo;
  const struct tvec_benchoutops *bo;
  BENCH_MEASURE_DECLS;
  struct bench_timing t;
  unsigned long *n;
  unsigned unit;
  double base;
  int rc;

  /* Decide on the kind of unit and the base count. */
  base = be->niter;
  if (be->rbuf < 0) unit = BTU_OP;
  else { unit = BTU_BYTE; base *= TVEC_REG(tv, in, be->rbuf)->v.bytes.sz; }

  /* Find the output operations and report the start. */
  bo = tvec_outputext(tv, &o, &fo,
		      TVEC_BENCHOUTEXT, &tvec_benchoutputfallback);
  bo->bbench(o, 0, unit);

  /* Run the benchmark. */
  if (be->riter >= 0) {
    n = &TVEC_REG(tv, in, be->riter)->v.u;
    if (subenv && subenv->run)
      BENCH_MEASURE(bc->bst, rc, &t, base)
	{ *n = _bench_n; subenv->run(tv, fn, bc->subctx); }
    else
      BENCH_MEASURE(bc->bst, rc, &t, base)
	{ *n = _bench_n; fn(tv->in, tv->out, bc->subctx); }
  } else {
    if (subenv && subenv->run)
      BENCH_MEASURE(bc->bst, rc, &t, base)
	while (_bench_n--) subenv->run(tv, fn, bc->subctx);
    else
      BENCH_MEASURE(bc->bst, rc, &t, base)
	while (_bench_n--) fn(tv->in, tv->out, bc->subctx);
  }

  /* Report the outcome. */
  bo->ebench(o, 0, unit, rc ? 0 : &t);
}

/* --- @tvec_benchafter@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@void *ctx@ = context pointer
 *
 * Returns:	---
 *
 * Use:		Invoke the subordinate environment's @after@ function to
 *		clean up after the benchmark.
 */

void tvec_benchafter(struct tvec_state *tv, void *ctx)
{
  struct tvec_benchctx *bc = ctx;
  const struct tvec_benchenv *be = bc->be;
  const struct tvec_env *subenv = be->env;

  /* Restore the benchmark state's old target. */
  if (bc->bst) bc->bst->target_s = bc->dflt_target;
  bc->f &= ~TVBF_SETTRG;

  /* Pass the call on to the subsidiary environment. */
  if (subenv && subenv->after) subenv->after(tv, bc->subctx);
}

/* --- @tvec_benchteardown@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@void *ctx@ = context pointer
 *
 * Returns:	---
 *
 * Use:		Tear down the benchmark environment.
 */

void tvec_benchteardown(struct tvec_state *tv, void *ctx)
{
  struct tvec_benchctx *bc = ctx;
  const struct tvec_benchenv *be;
  const struct tvec_env *subenv;

  be = bc->be; subenv = be->env;

  /* Tear down any subsidiary environment. */
  if (subenv && subenv->teardown) subenv->teardown(tv, bc->subctx);
  if (bc->subctx) x_free(tv->a, bc->subctx);

  /* If the benchmark state was temporary, then dispose of it. */
  if (bc->bst) {
    if (be->bst) bc->bst->target_s = bc->dflt_target;
    else { bench_destroy(bc->bst); x_free(tv->a, bc->bst); }
  }
}

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