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#
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#
pub struct ScaleA unit chosen for a column of values, so that the numbers of the column line up.
Field nanoseconds#
pub nanoseconds: f64How many of the base unit one unit holds: nanoseconds for a time, bytes for memory.
Field name#
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#
pub prefix: string<'static>What follows the number directly for any other unit: nothing, k, M or G.
Implementation Copy for Scale#
impl Copy for ScaleUnits#
pub struct UnitsThe owner type of the unit functions. It has no fields and is never constructed.
Implementation Units#
impl UnitsAssociated function scale#
pub fn scale(nanoseconds: f64) -> ScaleReturns the largest unit in which nanoseconds is 1 or more, or ns for less than 1 µs.
Associated function kind#
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#
pub fn higher(unit: string) -> boolReturns 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#
pub fn measure(value: f64, unit: string) -> ScaleReturns the scale in which value of the unit unit reads best: the largest one in which
it is 1 or more.
Associated function named#
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#
pub effect fn quantity(value: f64, unit: string) -> String
! OutOfMemoryError
? &mut AllocatorReturns 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#
pub effect fn appendFixed(text: &mut String, value: f64, decimals: usize) -> ()
! OutOfMemoryError
? &mut AllocatorAppends 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#
pub effect fn appendWhole(text: &mut String, value: u64) -> ()
! OutOfMemoryError
? &mut AllocatorAppends value to text in decimal.
Errors#
OutOfMemoryError if the Allocator cannot grow text.
Associated function appendSignificant#
pub effect fn appendSignificant(text: &mut String, value: f64) -> ()
! OutOfMemoryError
? &mut AllocatorAppends 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#
pub effect fn scaled(nanoseconds: f64, scale: Scale) -> String
! OutOfMemoryError
? &mut AllocatorReturns 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#
pub effect fn duration(nanoseconds: f64) -> String
! OutOfMemoryError
? &mut AllocatorReturns nanoseconds as text with its unit, such as 12.3 ms.
Errors#
OutOfMemoryError if the Allocator cannot supply the text.
Associated function memory#
pub effect fn memory(bytes: f64) -> String
! OutOfMemoryError
? &mut AllocatorReturns bytes as text in binary units, such as 4.20 MiB.
Errors#
OutOfMemoryError if the Allocator cannot supply the text.
Associated function ratio#
pub effect fn ratio(ratio: f64) -> String
! OutOfMemoryError
? &mut AllocatorReturns 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#
pub fn width(text: string) -> usizeReturns 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.