From a9aee1ce974ee9739de6a8589814d3f9dd0457dd Mon Sep 17 00:00:00 2001 From: Larpon Date: Fri, 18 Dec 2020 18:21:20 +0100 Subject: [PATCH] benchmark: document all functions (#7393) --- vlib/benchmark/benchmark.v | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/vlib/benchmark/benchmark.v b/vlib/benchmark/benchmark.v index a3afb53a06..296bce3f8e 100644 --- a/vlib/benchmark/benchmark.v +++ b/vlib/benchmark/benchmark.v @@ -26,6 +26,7 @@ pub mut: bfail string } +// new_benchmark returns a `Benchmark` instance on the stack. pub fn new_benchmark() Benchmark { return Benchmark{ bench_timer: time.new_stopwatch({}) @@ -33,6 +34,7 @@ pub fn new_benchmark() Benchmark { } } +// new_benchmark_no_cstep returns a new `Benchmark` instance with step counting disabled. pub fn new_benchmark_no_cstep() Benchmark { return Benchmark{ bench_timer: time.new_stopwatch({}) @@ -41,6 +43,8 @@ pub fn new_benchmark_no_cstep() Benchmark { } } +// new_benchmark_pointer returns a new `Benchmark` instance allocated on the heap. +// This is useful for long-lived use of `Benchmark` instances. pub fn new_benchmark_pointer() &Benchmark { return &Benchmark{ bench_timer: time.new_stopwatch({}) @@ -48,14 +52,17 @@ pub fn new_benchmark_pointer() &Benchmark { } } +// set_total_expected_steps sets the the total amount of steps the benchmark is expected to take. pub fn (mut b Benchmark) set_total_expected_steps(n int) { b.nexpected_steps = n } +// stop stops the internal benchmark timer. pub fn (mut b Benchmark) stop() { b.bench_timer.stop() } +// step increases the step count by 1 and restarts the internal timer. pub fn (mut b Benchmark) step() { b.step_timer.restart() if !b.no_cstep { @@ -63,46 +70,55 @@ pub fn (mut b Benchmark) step() { } } +// fail increases the fail count by 1 and stops the internal timer. pub fn (mut b Benchmark) fail() { b.step_timer.stop() b.ntotal++ b.nfail++ } +// ok increases the ok count by 1 and stops the internal timer. pub fn (mut b Benchmark) ok() { b.step_timer.stop() b.ntotal++ b.nok++ } +// skip increases the skip count by 1 and stops the internal timer. pub fn (mut b Benchmark) skip() { b.step_timer.stop() b.ntotal++ b.nskip++ } +// fail_many increases the fail count by `n` and stops the internal timer. pub fn (mut b Benchmark) fail_many(n int) { b.step_timer.stop() b.ntotal += n b.nfail += n } +// ok_many increases the ok count by `n` and stops the internal timer. pub fn (mut b Benchmark) ok_many(n int) { b.step_timer.stop() b.ntotal += n b.nok += n } +// neither_fail_nor_ok stops the internal timer. pub fn (mut b Benchmark) neither_fail_nor_ok() { b.step_timer.stop() } +// start returns a new, running, instance of `Benchmark`. +// This is a shorthand for calling `new_benchmark().step()`. pub fn start() Benchmark { mut b := new_benchmark() b.step() return b } +// measure prints the current time spent doing `label`, since the benchmark was started. pub fn (mut b Benchmark) measure(label string) i64 { b.ok() res := b.step_timer.elapsed().microseconds() @@ -111,6 +127,7 @@ pub fn (mut b Benchmark) measure(label string) i64 { return res } +// step_message_with_label_and_duration returns a string describing the current step. pub fn (b &Benchmark) step_message_with_label_and_duration(label string, msg string, sduration time.Duration) string { timed_line := b.tdiff_in_ms(msg, sduration.microseconds()) if b.nexpected_steps > 1 { @@ -137,26 +154,32 @@ pub fn (b &Benchmark) step_message_with_label_and_duration(label string, msg str return '${label:-5s}${timed_line}' } +// step_message_with_label returns a string describing the current step using current time as duration. pub fn (b &Benchmark) step_message_with_label(label string, msg string) string { return b.step_message_with_label_and_duration(label, msg, b.step_timer.elapsed()) } +// step_message returns a string describing the current step. pub fn (b &Benchmark) step_message(msg string) string { return b.step_message_with_label('', msg) } +// step_message_ok returns a string describing the current step with an standard "OK" label. pub fn (b &Benchmark) step_message_ok(msg string) string { return b.step_message_with_label(b_ok, msg) } +// step_message_fail returns a string describing the current step with an standard "FAIL" label. pub fn (b &Benchmark) step_message_fail(msg string) string { return b.step_message_with_label(b_fail, msg) } +// step_message_skip returns a string describing the current step with an standard "SKIP" label. pub fn (b &Benchmark) step_message_skip(msg string) string { return b.step_message_with_label(b_skip, msg) } +// total_message returns a string with total summary of the benchmark run. pub fn (b &Benchmark) total_message(msg string) string { mut tmsg := '${msg}\n ok, fail, skip, total = ' + term.ok_message('${b.nok:5d}') + ', ' + if b.nfail > 0 { term.red('${b.nfail:5d}') } else { '${b.nfail:5d}' } + ', ' + if b.nskip > 0 { term.bright_yellow('${b.nskip:5d}') } else { '${b.nskip:5d}' } + ', ' + '${b.ntotal:5d}' if b.verbose { @@ -172,12 +195,12 @@ pub fn (b &Benchmark) total_message(msg string) string { return spaces + b.tdiff_in_ms(tmsg, b.bench_timer.elapsed().microseconds()) } -// .total_duration - returns the duration in ms +// total_duration returns the duration in ms. pub fn (b &Benchmark) total_duration() i64 { return b.bench_timer.elapsed().milliseconds() } -// ////////////////////////////////////////////////////////////////// +// tdiff_in_ms prefixes `s` with a time difference calculation. fn (b &Benchmark) tdiff_in_ms(s string, tdiff i64) string { if b.verbose { return '${f64(tdiff)/1000.0:9.3f} ms $s'