silk.bench.view.
Says how the results of a benchmark suite should be shown: a kind of chart and the fields it maps.
When to use#
Add a View to a suite with silk.bench.suite.Suite.view when the default presentation
is not the one a reader needs: a line against an input size, a comparison against another
implementation than the reference, every sample of a noisy benchmark, or a chart of your
own kind.
Details#
A view holds no numbers and no code. It names a kind and sets fields, and the report
resolves it into a silk.bench.record.Chart with every number computed, which the
renderers only draw.
| Kind | Shows |
|---|---|
table | One value for each benchmark and implementation |
ratio | Values relative to the reference, with interval whiskers |
bars | Absolute values with whiskers |
distribution | Every sample, warm-up runs dimmed |
line | A value against a parameter of the suite |
percentiles | A value against the percentile of the samples |
history | A value against the recorded runs of the suite |
x-<name> | Anything: the built-in renderers show it as a table |
The fields are the same for every kind, and a kind ignores the ones that mean nothing to it:
| Field | Value | Default |
|---|---|---|
y | The unit to show, such as ns/op. A command suite has ns, user-ns, sys-ns and peak-B | The unit of the tables |
x | What runs along the axis: benchmark, name, impl, or a parameter | benchmark; the parameter of a line |
series | What each line or bar group is: the same choices as x | impl |
facet | What each separate chart is | Whatever x and series leave |
stat | median, min, max, mean, or a percentile such as p99 | median |
error | interval (the 95% interval of the median), range, or none | interval |
scale | linear, log (the value axis), or log-log (both axes) | linear |
zero | true to start the value axis at zero, false to fit the values | true |
normalize | An implementation to divide every value by | The reference in a ratio |
sort | value or -value to order the entries of x by their first series | The order they ran in |
title | The heading | Written from the kind and the fields |
A view has a text form, View.text, which is one line: the kind, then field=value
pairs. A program that prints result lines may print view: line x=size y=ns/op to suggest
a view; the views a suite declares win over the ones its programs suggest.
Examples#
import silk.bench.view { View }
import silk.core.effect { Effect }
import silk.mem.allocator { Allocator, OutOfMemoryError }
// A view written in the tasks program is the same as the line a program prints.
effect fn check() -> i32 ! OutOfMemoryError ? &mut Allocator {
let mut view = run View.line("size")
run view.y("ns/op")
run view.logLog()
let text = run view.text()
if text.view() != "line x=size y=ns/op scale=log-log" {
return 1
}
let read = run View.parse("line x=size y=ns/op scale=log-log")
let again = run read.text()
if again.view() != text.view() {
return 2
}
return 0
}
effect fn failed(error: OutOfMemoryError) -> i32 {
drop error
return 3
}
pub fn main() -> i32 {
let mut allocator = Allocator.systemAllocatorProvider()
return run Effect.catchAll(check(), failed) |> Effect.provideMut<Allocator>(&mut allocator)
}Import as View with import silk.bench.view { View }.
Public declarations: 1.
View#
pub struct ViewA presentation of the results of a suite: a kind of chart and the fields it maps.
Details#
The fields are public so a tool can read a view. Build one with the functions named after
the kinds, such as View.line, and set fields with the methods below.
Field kind#
pub kind: StringThe kind, such as line or x-flame.
Field fields#
pub fields: List<Pair>The fields that were set, in the order they were first set.
Implementation View#
impl ViewAssociated function of#
pub effect fn of(kind: string) -> View
! OutOfMemoryError
? &mut AllocatorReturns a view of kind with no field set. A kind the report does not know is resolved
like table, so name your own kinds x-<name>.
Associated function table#
pub effect fn table() -> View
! OutOfMemoryError
? &mut AllocatorReturns a view that shows one value for each benchmark and implementation as a table.
Associated function ratio#
pub effect fn ratio() -> View
! OutOfMemoryError
? &mut AllocatorReturns a view that shows every implementation relative to the reference, with the interval of the ratio as whiskers.
Associated function bars#
pub effect fn bars() -> View
! OutOfMemoryError
? &mut AllocatorReturns a view that shows absolute values as bars with whiskers.
Associated function distribution#
pub effect fn distribution() -> View
! OutOfMemoryError
? &mut AllocatorReturns a view that shows every sample, with the warm-up runs dimmed, to check for two modes or for drift.
Associated function line#
pub effect fn line(x: string) -> View
! OutOfMemoryError
? &mut AllocatorReturns a view that shows a value against the parameter x of the suite, such as an
input size or a thread count.
Associated function percentiles#
pub effect fn percentiles() -> View
! OutOfMemoryError
? &mut AllocatorReturns a view that shows a value against the percentile of the samples, as a load test reads its latencies.
Details#
When the result lines carry units such as p50-ns and p99-ns and the view's y is
ns, the chart shows what the lines report. Otherwise the percentiles are taken from the
samples of y.
Associated function history#
pub effect fn history() -> View
! OutOfMemoryError
? &mut AllocatorReturns a view that shows a value against the recorded runs of the suite, with the run being reported last.
Associated function custom#
pub effect fn custom(name: string) -> View
! OutOfMemoryError
? &mut AllocatorReturns a view of the kind x-<name>, for a renderer of your own. The report resolves it
like table and carries every field through, also the ones it does not know.
Associated function parse#
pub effect fn parse(text: string) -> View
! OutOfMemoryError
? &mut AllocatorReturns the view that text describes: a kind, then field=value pairs separated by
spaces. A value with spaces is written in double quotes, with \" for a quote inside it.
Text without a kind gives a table.
Method field#
pub effect fn field(self: &mut Self, name: string, value: string) -> ()
! OutOfMemoryError
? &mut AllocatorSets the field name to value, replacing what it was set to before. The methods below
set the fields the report knows; this one also sets a field of your own.
Method value#
pub fn value<'view>(self: &'view Self, name: string) -> Option<string<'view>>Returns what the field name was set to, if it was set.
Method title#
pub effect fn title(self: &mut Self, text: string) -> ()
! OutOfMemoryError
? &mut AllocatorSets the heading.
Method y#
pub effect fn y(self: &mut Self, unit: string) -> ()
! OutOfMemoryError
? &mut AllocatorSets the unit to show, such as ns/op or req/s.
Method x#
pub effect fn x(self: &mut Self, name: string) -> ()
! OutOfMemoryError
? &mut AllocatorSets what runs along the axis: benchmark, name, impl, or the name of a parameter.
Method series#
pub effect fn series(self: &mut Self, name: string) -> ()
! OutOfMemoryError
? &mut AllocatorSets what each line or group of bars is: impl, benchmark, name, or the name of a
parameter.
Method facet#
pub effect fn facet(self: &mut Self, name: string) -> ()
! OutOfMemoryError
? &mut AllocatorSets what each separate chart is: impl, benchmark, name, or the name of a
parameter.
Method stat#
pub effect fn stat(self: &mut Self, name: string) -> ()
! OutOfMemoryError
? &mut AllocatorSets the statistic of the samples to show: median, min, max, mean, or a
percentile such as p99.
Method error#
pub effect fn error(self: &mut Self, name: string) -> ()
! OutOfMemoryError
? &mut AllocatorSets what the whiskers show: interval, range, or none.
Method log#
pub effect fn log(self: &mut Self) -> ()
! OutOfMemoryError
? &mut AllocatorPuts the value axis on a logarithmic scale.
Method logLog#
pub effect fn logLog(self: &mut Self) -> ()
! OutOfMemoryError
? &mut AllocatorPuts both axes on a logarithmic scale.
Method zero#
pub effect fn zero(self: &mut Self, start: bool) -> ()
! OutOfMemoryError
? &mut AllocatorSays whether the value axis starts at zero. Without it, the axis starts at zero unless its scale is logarithmic.
Method normalize#
pub effect fn normalize(self: &mut Self, implementation: string) -> ()
! OutOfMemoryError
? &mut AllocatorDivides every value by the value of implementation in the same benchmark.
Method sort#
pub effect fn sort(self: &mut Self, order: string) -> ()
! OutOfMemoryError
? &mut AllocatorOrders the entries of x by the value of their first series: value puts the smallest
first and -value the largest.
Method text#
pub effect fn text(self: &Self) -> String
! OutOfMemoryError
? &mut AllocatorReturns the view as one line: the kind, then field=value pairs. View.parse reads it
back.
Category: Benchmarks.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.