@@@ tvec doc wip

[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"

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

/*----- Utilities ---------------------------------------------------------*/

/* --- @normalize@ --- *
 *
 * Arguments:	@double *x_inout@ = address of a value to normalize
 *		@const char **unit_out@ = address to store unit prefix
 *		@double scale@ = scale factor for unit steps
 *
 * Returns:	---
 *
 * Use:		Adjust @*x_inout@ by a power of @scale@, and set @*unit_out@
 *		so that printing the two reflects the original value with an
 *		appropriate SI unit scaling.  The @scale@ should be 1024 for
 *		binary quantities, most notably memory sizes, or 1000 for
 *		other quantities.
 */

static void normalize(double *x_inout, const char **unit_out, double scale)
{
  static const char
    *const nothing = "",
    *const big[] = { "k", "M", "G", "T", "P", "E", 0 },
    *const little[] = { "m", "µ", "n", "p", "f", "a", 0 };
  const char *const *u;
  double x = *x_inout;

  if (x < 1)
    for (u = little, x *= scale; x < 1 && u[1]; u++, x *= scale);
  else if (x >= scale)
    for (u = big, x /= scale; x >= scale && u[1]; u++, x /= scale);
  else
    u = &nothing;

  *x_inout = x; *unit_out = *u;
}

/* --- @benchloop_...@ --- *
 *
 * Arguments:	@unsigned long n@ = iteration count
 *		@void *ctx@ = benchmark running context
 *
 * Returns:	---
 *
 * Use:		Run various kinds of benchmarking loops.
 *
 *		  * The @..._outer_...@ functions call the underlying
 *		    function @n@ times in a loop; by contrast, the
 *		    @..._inner_...@ functions set a register value to the
 *		    chosen iteration count and expect the underlying function
 *		    to perform the loop itself.
 *
 *		  * The @..._direct@ functions just call the underlying test
 *		    function directly (though still through an `indirect
 *		    jump' instruction); by contrast, the @..._indirect@
 *		    functions invoke a subsidiary environment's @run@
 *		    function, which adds additional overhead.
 */

static void benchloop_outer_direct(unsigned long n, void *ctx)
{
  struct benchrun *r = ctx;
  tvec_testfn *fn = r->fn; void *tctx = r->ctx;
  const struct tvec_reg *in = r->in; struct tvec_reg *out = r->out;

  while (n--) fn(in, out, tctx);
}

static void benchloop_inner_direct(unsigned long n, void *ctx)
  { struct benchrun *r = ctx; *r->n = n; r->fn(r->in, r->out, r->ctx); }

static void benchloop_outer_indirect(unsigned long n, void *ctx)
{
  struct benchrun *r = ctx;
  struct tvec_state *tv = r->tv;
  void (*run)(struct tvec_state *, tvec_testfn, void *) = r->env->run;
  tvec_testfn *fn = r->fn; void *tctx = r->ctx;

  while (n--) run(tv, fn, tctx);
}

static void benchloop_inner_indirect(unsigned long n, void *ctx)
  { struct benchrun *r = ctx; *r->n = n; r->env->run(r->tv, r->fn, r->ctx); }

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

/* --- @tvec_benchreport@ --- *
 *
 * Arguments:	@const struct gprintf_ops *gops@ = print operations
 *		@void *go@ = print destination
 *		@unsigned unit@ = the unit being measured (~TVBU_...@)
 *		@const struct bench_timing *tm@ = 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, const struct bench_timing *tm)
{
  double scale, x, n = tm->n;
  const char *u, *what, *whats;

  if (!tm) { gprintf(gops, go, "benchmark FAILED"); return; }

  assert(tm->f&BTF_TIMEOK);

  switch (unit) {
    case TVBU_OP:
      gprintf(gops, go, "%.0f iterations ", n);
      what = "op"; whats = "ops"; scale = 1000;
      break;
    case TVBU_BYTE:
      x = n; normalize(&x, &u, 1024); gprintf(gops, go, "%.3f %sB ", x, u);
      what = whats = "B"; scale = 1024;
      break;
    default:
      abort();
  }

  x = tm->t; normalize(&x, &u, 1000);
  gprintf(gops, go, "in %.3f %ss", x, u);
  if (tm->f&BTF_CYOK) {
    x = tm->cy; normalize(&x, &u, 1000);
    gprintf(gops, go, " (%.3f %scy)", x, u);
  }
  gprintf(gops, go, ": ");

  x = n/tm->t; normalize(&x, &u, scale);
  gprintf(gops, go, "%.3f %s%s/s", x, u, whats);
  x = tm->t/n; normalize(&x, &u, 1000);
  gprintf(gops, go, ", %.3f %ss/%s", x, u, what);
  if (tm->f&BTF_CYOK) {
    x = tm->cy/n; normalize(&x, &u, 1000);
    gprintf(gops, go, " (%.3f %scy/%s)", x, u, what);
  }
}

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

/* --- @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;
  struct bench_timer *bt;

  /* Basic initialization. */
  bc->be = be; bc->bst = 0; bc->subctx = 0;

  /* Set up the benchmarking state if it hasn't been done before. */
  if (!be->bst || !*be->bst) {
    bt = bench_createtimer(); if (!bt) goto fail_timer;
    bc->bst = xmalloc(sizeof(*bc->bst)); bench_init(bc->bst, bt);
    if (be->bst) *be->bst = bc->bst;
  } else if (!(*be->bst)->tm)
    goto fail_timer;
  else
    bc->bst = *be->bst;

  /* Set the default target time. */
  bc->dflt_target = bc->bst->target_s;

  /* Initialize the subordinate environment. */
  if (subenv && subenv->ctxsz) bc->subctx = xmalloc(subenv->ctxsz);
  if (subenv && subenv->setup) subenv->setup(tv, subenv, bc, bc->subctx);

  /* All done. */
end:
  return;
fail_timer:
  tvec_skipgroup(tv, "failed to create timer"); goto end;
}

/* --- @tvec_benchset@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@const char *var@ = variable name to set
 *		@void *ctx@ = context pointer
 *
 * Returns:	%$+1$% on success, %$0$% if the variable name was not
 *		recognized, or %$-1$% on any other error.
 *
 * Use:		Set a special variable.  The following special variables are
 *		supported.
 *
 *		  * %|@target|% is the (approximate) number of seconds to run
 *		    the benchmark.
 *
 *		Unrecognized variables are passed to the subordinate
 *		environment, if there is one.
 */

int tvec_benchset(struct tvec_state *tv, const char *var, void *ctx)
{
  struct tvec_benchctx *bc = ctx;
  const struct tvec_benchenv *be = bc->be;
  const struct tvec_env *subenv = be->env;
  union tvec_regval rv;
  static const struct tvec_floatinfo fi = { TVFF_NOMAX, 0.0, 0.0, 0.0 };
  static const struct tvec_regdef rd =
    { "@target", -1, &tvty_float, 0, { &fi } };

  if (STRCMP(var, ==, "@target")) {
    if (bc->f&TVBF_SETTRG) return (tvec_dupreg(tv, var));
    if (tvty_float.parse(&rv, &rd, tv)) return (-1);
    bc->bst->target_s = rv.f; bc->f |= TVBF_SETTRG; return (1);
  } else if (subenv && subenv->set)
    return (subenv->set(tv, var, 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;

  /* Just call the subsidiary environment. */
  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;
  const struct tvec_regdef *rd;
  struct tvec_output *o = tv->output;
  struct bench_timing tm;
  struct benchrun r;
  bench_fn *loopfn;
  unsigned unit;
  dstr d = DSTR_INIT;
  double base;
  unsigned f = 0;
#define f_any 1u

  /* Fill in the easy parts of the run context. */
  r.tv = tv; r.env = subenv; r.ctx = bc->subctx;
  r.in = tv->in; r.out = tv->out; r.fn = fn;

  /* Decide on the run function to select. */
  if (be->riter >= 0) {
    r.n = &TVEC_REG(tv, in, be->riter)->v.u;
    loopfn = subenv && subenv->run ?
      benchloop_inner_indirect : benchloop_inner_direct;
  } else {
    r.n = 0;
    loopfn = subenv && subenv->run ?
      benchloop_outer_indirect : benchloop_outer_direct;
  }

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

  /* Construct a description of the test using the identifier registers. */
  for (rd = tv->test->regs; rd->name; rd++)
    if (rd->f&TVRF_ID) {
      if (f&f_any) dstr_puts(&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);
    }

  /* Run the benchmark. */
  o->ops->bbench(o, d.buf, unit);
  if (bench_measure(&tm, bc->bst, base, loopfn, &r))
    o->ops->ebench(o, d.buf, unit, 0);
  else
    o->ops->ebench(o, d.buf, unit, &tm);

  dstr_destroy(&d);

#undef f_any
}

/* --- @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. */
  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 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); xfree(bc->bst); }
  }
}

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