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