silk.bench.units.

Text for the quantities of a benchmark report: durations, memory sizes, and ratios.

When to use#

Use Units in a renderer of your own, so its numbers read like those of the built-in reports: 12.3 ms, 4.20 MiB, 0.49x.

Details#

A duration is given in nanoseconds and written with three significant digits in the largest unit that keeps it at 1 or more: ns, µs, ms, or s. A Scale fixes the unit, so the numbers of one column share it and line up. Memory is given in bytes and written in binary units: KiB, MiB, GiB.

Examples#

silk
import silk.bench.units { Units }
import silk.core.effect { Effect }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.text.string { String }

effect fn check() -> i32 ! OutOfMemoryError ? &mut Allocator {
  let time = run Units.duration(12345678.0)
  let size = run Units.memory(4404019.0)
  if String.view(&time) == "12.3 ms" && String.view(&size) == "4.20 MiB" {
    return 0
  }
  return 1
}

effect fn failed(error: OutOfMemoryError) -> i32 {
  drop error
  return 2
}

pub fn main() -> i32 {
  let mut allocator = Allocator.systemAllocatorProvider()
  return run Effect.catchAll(check(), failed) |> Effect.provideMut<Allocator>(&mut allocator)
}

Import as Units with import silk.bench.units { Units }.

Public declarations: 2.

Scale#

silk
pub struct Scale

A unit chosen for a column of values, so that the numbers of the column line up.

Field nanoseconds#

silk
pub nanoseconds: f64

How many of the base unit one unit holds: nanoseconds for a time, bytes for memory.

Field name#

silk
pub name: string<'static>

The unit's name: ns, µs, ms or s for a time, B, KiB, MiB or GiB for memory. Empty for any other unit, which keeps the name the program gave it.

Field prefix#

silk
pub prefix: string<'static>

What follows the number directly for any other unit: nothing, k, M or G.

Implementation Copy for Scale#

silk
impl Copy for Scale

Units#

silk
pub struct Units

The owner type of the unit functions. It has no fields and is never constructed.

Implementation Units#

silk
impl Units

Associated function scale#

silk
pub fn scale(nanoseconds: f64) -> Scale

Returns the largest unit in which nanoseconds is 1 or more, or ns for less than 1 µs.

Associated function kind#

silk
pub fn kind(unit: string) -> string<'static>

Returns the kind of the unit unit, which decides how its values are scaled: ns for a time in nanoseconds, B for bytes, and nothing for any other unit.

Details#

What counts is the text before the first /, after a qualifier that ends with -. So ns/op, user-ns/op and ns are times, and B/op and peak-B are bytes.

Associated function higher#

silk
pub fn higher(unit: string) -> bool

Returns whether a larger value of the unit unit is better: a unit that ends with /s or /sec, such as req/s or MB/s. For every other unit, smaller is better.

Associated function measure#

silk
pub fn measure(value: f64, unit: string) -> Scale

Returns the scale in which value of the unit unit reads best: the largest one in which it is 1 or more.

Associated function named#

silk
pub fn named<'unit>(scale: Scale, unit: string<'unit>) -> string<'unit>

Returns the name that follows the numbers of a column in scale: the scale's own name for a time or memory, and unit as it is for any other unit.

Associated function quantity#

silk
pub effect fn quantity(value: f64, unit: string) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns value of the unit unit as text with its unit, such as 12.3 ms, 4.20 MiB or 74.2k req/s.

Errors#

OutOfMemoryError if the Allocator cannot supply the text.

Associated function appendFixed#

silk
pub effect fn appendFixed(text: &mut String, value: f64, decimals: usize) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends value to text with decimals digits after the point, rounded half away from zero. A value that is not finite is written as -.

Errors#

OutOfMemoryError if the Allocator cannot grow text.

Associated function appendWhole#

silk
pub effect fn appendWhole(text: &mut String, value: u64) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends value to text in decimal.

Errors#

OutOfMemoryError if the Allocator cannot grow text.

Associated function appendSignificant#

silk
pub effect fn appendSignificant(text: &mut String, value: f64) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends value to text with three significant digits: 1.23, 12.3, or 123. Values of 1000 or more keep all their whole digits.

Errors#

OutOfMemoryError if the Allocator cannot grow text.

Associated function scaled#

silk
pub effect fn scaled(nanoseconds: f64, scale: Scale) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns nanoseconds, a value in the base unit of scale, as text in the unit of scale, without the unit's name, such as 12.3, or 74.2k for a scale with a prefix.

Errors#

OutOfMemoryError if the Allocator cannot supply the text.

Associated function duration#

silk
pub effect fn duration(nanoseconds: f64) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns nanoseconds as text with its unit, such as 12.3 ms.

Errors#

OutOfMemoryError if the Allocator cannot supply the text.

Associated function memory#

silk
pub effect fn memory(bytes: f64) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns bytes as text in binary units, such as 4.20 MiB.

Errors#

OutOfMemoryError if the Allocator cannot supply the text.

Associated function ratio#

silk
pub effect fn ratio(ratio: f64) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns ratio as text with two decimals and an x, such as 0.49x.

Errors#

OutOfMemoryError if the Allocator cannot supply the text.

Associated function width#

silk
pub fn width(text: string) -> usize

Returns the number of characters of text, which is the number of terminal columns it takes when it holds no wide or combining characters.

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