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.

KindShows
tableOne value for each benchmark and implementation
ratioValues relative to the reference, with interval whiskers
barsAbsolute values with whiskers
distributionEvery sample, warm-up runs dimmed
lineA value against a parameter of the suite
percentilesA value against the percentile of the samples
historyA 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:

FieldValueDefault
yThe unit to show, such as ns/op. A command suite has ns, user-ns, sys-ns and peak-BThe unit of the tables
xWhat runs along the axis: benchmark, name, impl, or a parameterbenchmark; the parameter of a line
seriesWhat each line or bar group is: the same choices as ximpl
facetWhat each separate chart isWhatever x and series leave
statmedian, min, max, mean, or a percentile such as p99median
errorinterval (the 95% interval of the median), range, or noneinterval
scalelinear, log (the value axis), or log-log (both axes)linear
zerotrue to start the value axis at zero, false to fit the valuestrue
normalizeAn implementation to divide every value byThe reference in a ratio
sortvalue or -value to order the entries of x by their first seriesThe order they ran in
titleThe headingWritten 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#

silk
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#

silk
pub struct View

A 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#

silk
pub kind: String

The kind, such as line or x-flame.

Field fields#

silk
pub fields: List<Pair>

The fields that were set, in the order they were first set.

Implementation View#

silk
impl View

Associated function of#

silk
pub effect fn of(kind: string) -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns 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#

silk
pub effect fn table() -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns a view that shows one value for each benchmark and implementation as a table.

Associated function ratio#

silk
pub effect fn ratio() -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns a view that shows every implementation relative to the reference, with the interval of the ratio as whiskers.

Associated function bars#

silk
pub effect fn bars() -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns a view that shows absolute values as bars with whiskers.

Associated function distribution#

silk
pub effect fn distribution() -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns a view that shows every sample, with the warm-up runs dimmed, to check for two modes or for drift.

Associated function line#

silk
pub effect fn line(x: string) -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns 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#

silk
pub effect fn percentiles() -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns 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#

silk
pub effect fn history() -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns a view that shows a value against the recorded runs of the suite, with the run being reported last.

Associated function custom#

silk
pub effect fn custom(name: string) -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns 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#

silk
pub effect fn parse(text: string) -> View
    ! OutOfMemoryError
    ? &mut Allocator

Returns 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#

silk
pub effect fn field(self: &mut Self, name: string, value: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets 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#

silk
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#

silk
pub effect fn title(self: &mut Self, text: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the heading.

Method y#

silk
pub effect fn y(self: &mut Self, unit: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the unit to show, such as ns/op or req/s.

Method x#

silk
pub effect fn x(self: &mut Self, name: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets what runs along the axis: benchmark, name, impl, or the name of a parameter.

Method series#

silk
pub effect fn series(self: &mut Self, name: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets what each line or group of bars is: impl, benchmark, name, or the name of a parameter.

Method facet#

silk
pub effect fn facet(self: &mut Self, name: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets what each separate chart is: impl, benchmark, name, or the name of a parameter.

Method stat#

silk
pub effect fn stat(self: &mut Self, name: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the statistic of the samples to show: median, min, max, mean, or a percentile such as p99.

Method error#

silk
pub effect fn error(self: &mut Self, name: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets what the whiskers show: interval, range, or none.

Method log#

silk
pub effect fn log(self: &mut Self) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Puts the value axis on a logarithmic scale.

Method logLog#

silk
pub effect fn logLog(self: &mut Self) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Puts both axes on a logarithmic scale.

Method zero#

silk
pub effect fn zero(self: &mut Self, start: bool) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Says whether the value axis starts at zero. Without it, the axis starts at zero unless its scale is logarithmic.

Method normalize#

silk
pub effect fn normalize(self: &mut Self, implementation: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Divides every value by the value of implementation in the same benchmark.

Method sort#

silk
pub effect fn sort(self: &mut Self, order: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Orders the entries of x by the value of their first series: value puts the smallest first and -value the largest.

Method text#

silk
pub effect fn text(self: &Self) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns 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.

View the source of this page