5 * (c) 2023 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of the mLib utilities library.
12 * mLib is free software: you can redistribute it and/or modify it under
13 * the terms of the GNU Library General Public License as published by
14 * the Free Software Foundation; either version 2 of the License, or (at
15 * your option) any later version.
17 * mLib is distributed in the hope that it will be useful, but WITHOUT
18 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
20 * License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with mLib. If not, write to the Free Software
24 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
35 /*----- Header files ------------------------------------------------------*/
41 /*----- Data structures ---------------------------------------------------*/
44 unsigned f; /* flags */
45 #define BTF_TIMEOK 1u /* @s@ ad @ns@ slots are value */
46 #define BTF_CYOK 2u /* @cy@ slot is valid */
47 #define BTF_ANY (BTF_TIMEOK | BTF_CYOK) /* some part is useful */
48 kludge64 s; uint32 ns; /* real time, seconds and nanos */
49 kludge64 cy; /* count of CPU cycles */
53 unsigned f; /* flags (@BTF_...@) */
54 double n, t, cy; /* count, time, and cycles */
57 struct bench_timer { const struct bench_timerops *ops; };
59 struct bench_timerops {
60 void (*now)(struct bench_timer */*bt*/, struct bench_time */*t_out*/);
61 /* Fill in @*t_out@ with the current time. v*/
63 void (*destroy)(struct bench_timer */*bt*/);
64 /* Release the timer and any resources it holds. */
68 struct bench_timer *tm; /* a timer */
69 double target_s; /* target time to run benchmarks */
70 unsigned f; /* calibration flags (@BTF_...@) */
71 struct { double m, c; } clk, cy; /* calculated overheads */
74 typedef void bench_fn(unsigned long /*n*/, void */*ctx*/);
75 /* Run the benchmark @n@ times, given a context pointer @ctx@. */
77 /*----- Functions provided ------------------------------------------------*/
79 /* --- @bench_createtimer@ --- *
83 * Returns: A freshly constructed standard timer object.
85 * Use: Allocate a timer. Dispose of it by calling
86 * @tm->ops->destroy(tm)@ when you're done.
89 extern struct bench_timer *bench_createtimer(void);
91 /* --- @bench_init@ --- *
93 * Arguments: @struct bench_state *b@ = bench state to initialize
94 * @struct bench_timer *tm@ = timer to attach
98 * Use: Initialize the benchmark state. It still needs to be
99 * calibrated (use @bench_calibrate@) before it can be used, but
100 * this will be done automatically by @bench_measure@ if it's
101 * not done by hand earlier. The timer is now owned by the
102 * benchmark state and will be destroyed by @bench_destroy@.
105 extern void bench_init(struct bench_state */*b*/,
106 struct bench_timer */*tm*/);
108 /* --- @bench_destroy@ --- *
110 * Arguments: @struct bench_state *b@ = bench state
114 * Use: Destroy the benchmark state, releasing the resources that it
118 extern void bench_destroy(struct bench_state */*b*/);
120 /* --- @bench_calibrate@ --- *
122 * Arguments: @struct bench_state *b@ = bench state
124 * Returns: Zero on success, @-1@ if calibration failed.
126 * Use: Calibrate the benchmark state, so that it can be used to
127 * measure performance reasonably accurately.
130 extern int bench_calibrate(struct bench_state */*b*/);
132 /* --- @bench_measure@ --- *
134 * Arguments: @struct bench_timing *t_out@ = where to leave the timing
135 * @struct bench_state *b@ = benchmark state
136 * @double base@ = number of internal units per call
137 * @bench_fn *fn@, @void *ctx@ = benchmark function to run
139 * Returns: Zero on success, @-1@ if timing failed.
141 * Use: Measure a function. The function @fn@ is called adaptively
142 * with an iteration count @n@ set so as to run for
143 * approximately @b->target_s@ seconds.
145 * The result is left in @*t_out@, with @t_out->n@ counting the
146 * final product of the iteration count and @base@ (which might,
147 * e.g., reflect the number of inner iterations the function
148 * performs, or the number of bytes it processes per iteration).
151 extern int bench_measure(struct bench_timing */*t_out*/,
152 struct bench_state */*b*/,
153 double /*base*/, bench_fn */*fn*/, void */*ctx*/);
155 /*----- That's all, folks -------------------------------------------------*/