benchmark #

Description

benchmark provides tools for measuring and reporting on the performance of code.

Example 1

import benchmark

mut bmark := benchmark.new_benchmark()
// by default the benchmark will be verbose, i.e. it will include timing information
// if you want it to be silent, set bmark.verbose = false
for {
    bmark.step() // call this when you want to advance the benchmark.
    // The timing info in bmark.step_message will be measured starting from the last call to bmark.step
    // ....
    // bmark.fail() // call this if the step failed
    // bmark.step_message(('failed')
    bmark.ok() // call this when the step succeeded
    println(bmark.step_message('ok'))
}
bmark.stop()
// call when you want to finalize the benchmark
println(bmark.total_message('remarks about the benchmark'))

.start() and .measure() are convenience methods, intended to be used in combination. Their goal is to make benchmarking of small snippets of code as short, easy to write, and easy to read and analyze as possible.

Example 2

import time
import benchmark

mut b := benchmark.start()
// your code section 1 ...
time.sleep(1500 * time.millisecond)
b.measure('code_1')
// your code section 2 ...
time.sleep(500 * time.millisecond)
b.measure('code_2')

... which will produce on stdout something like this:

SPENT 1500.063 ms in code_1
SPENT  500.061 ms in code_2

fn new_benchmark() Benchmark

new_benchmark returns a Benchmark instance on the stack.

fn new_benchmark_no_cstep() Benchmark

new_benchmark_no_cstep returns a new Benchmark instance with step counting disabled.

fn new_benchmark_pointer() &Benchmark

new_benchmark_pointer returns a new Benchmark instance allocated on the heap. This is useful for long-lived use of Benchmark instances.

fn start() Benchmark

start returns a new, running, instance of Benchmark. This is a shorthand for calling new_benchmark().step().

struct Benchmark {
pub mut:
	bench_timer     time.StopWatch
	verbose         bool
	no_cstep        bool
	step_timer      time.StopWatch
	ntotal          int
	nok             int
	nfail           int
	nskip           int
	nexpected_steps int
	njobs           int
	cstep           int
	bok             string
	bfail           string
	measured_steps  []string
	step_data       map[string][]f64
}

fn (mut b Benchmark) set_total_expected_steps(n int)

set_total_expected_steps sets the total amount of steps the benchmark is expected to take.

fn (mut b Benchmark) stop()

stop stops the internal benchmark timer.

fn (mut b Benchmark) step()

step increases the step count by 1 and restarts the internal timer.

fn (mut b Benchmark) step_restart()

step_restart will restart the internal step timer. Note that the step count will stay the same. This method is useful, when you want to do some optional preparation after you have called .step(), so that the time for that optional preparation will not be added to the duration of the step.

fn (mut b Benchmark) fail()

fail increases the fail count by 1 and stops the internal timer.

fn (mut b Benchmark) ok()

ok increases the ok count by 1 and stops the internal timer.

fn (mut b Benchmark) skip()

skip increases the skip count by 1 and stops the internal timer.

fn (mut b Benchmark) fail_many(n int)

fail_many increases the fail count by n and stops the internal timer.

fn (mut b Benchmark) ok_many(n int)

ok_many increases the ok count by n and stops the internal timer.

fn (mut b Benchmark) neither_fail_nor_ok()

neither_fail_nor_ok stops the internal timer.

fn (mut b Benchmark) measure(label string) i64

measure prints the current time spent doing label, since the benchmark was started, or since its last call

fn (mut b Benchmark) record_measure(label string) i64

record_measure stores the current time doing label, since the benchmark was started, or since the last call to b.record_measure. It is similar to b.measure, but unlike it, will not print the measurement immediately, just record it for later. You can call b.all_recorded_measures to retrieve all measures stored by b.record_measure calls.

fn (b &Benchmark) step_message_with_label_and_duration(label string, msg string, sduration time.Duration,
	opts MessageOptions) string

step_message_with_label_and_duration returns a string describing the current step.

fn (b &Benchmark) step_message_with_label(label string, msg string, opts MessageOptions) string

step_message_with_label returns a string describing the current step using current time as duration.

fn (b &Benchmark) step_message(msg string, opts MessageOptions) string

step_message returns a string describing the current step.

fn (b &Benchmark) step_message_ok(msg string, opts MessageOptions) string

step_message_ok returns a string describing the current step with an standard "OK" label.

fn (b &Benchmark) step_message_fail(msg string, opts MessageOptions) string

step_message_fail returns a string describing the current step with an standard "FAIL" label.

fn (b &Benchmark) step_message_skip(msg string, opts MessageOptions) string

step_message_skip returns a string describing the current step with an standard "SKIP" label.

fn (b &Benchmark) total_message(msg string) string

total_message returns a string with total summary of the benchmark run.

fn (b &Benchmark) all_recorded_measures() string

all_recorded_measures returns a string, that contains all the recorded measure messages, done by individual calls to b.record_measure.

fn (b &Benchmark) total_duration() i64

total_duration returns the duration in ms.

struct MessageOptions {
pub:
	preparation time.Duration // the duration of the preparation time for the step
}

MessageOptions allows passing an optional preparation time too to each label method. If it is set, the preparation time (compile time) will be shown before the measured runtime.