silk.bench.transport.
Carries the lines of the driven benchmark protocol between a benchmark task and a harness.
When to use#
Provide a StreamTransport to a silk.bench.harness.Harness so that a benchmark task can
drive your program. Implement Transport yourself to drive a harness that standard input
and output cannot reach: one on another computer behind a socket, or one in a sandbox that
only shares files.
Details#
The driven protocol is a dialogue of lines, and this service is all of it that touches the
outside: Transport.receive takes the next line from the other side, and
Transport.send gives it one. Neither side of the protocol knows what carries the lines.
The task sends one command a line, and the harness answers each with lines that end with
the line done:
task list
harness BenchmarkParse/file=twitter
harness BenchmarkWrite
harness done
task run BenchmarkParse/file=twitter 2000
harness BenchmarkParse/file=twitter 2000 165412.50 ns/op
harness done
task quitlistasks for the names of the benchmarks, one a line.run <name> <iterations>asks for one sample: the harness runs the body that many times and answers with one result line, assilk.bench.linesdescribes them. It may send configuration lines such ascheck: 9f2c41aabefore the result line.quitends the harness. The end of the input means the same.
A harness in another language reads and writes these lines on its standard input and
output. The task starts it with the environment variable BENCH_DRIVE set to 1.
StreamTransport carries the lines over two descriptors: StreamTransport.standard is
standard input and output, which is what a harness uses, and StreamTransport.over is any
pair, which is what the task uses for the pipes of a harness it started.
Gotchas#
StreamTransport works on Linux with GNU libc and on macOS. On another system, every
operation fails.
Examples#
import silk.bench.transport { Transport, TransportError }
import silk.collections.list { List }
import silk.core.effect { Effect }
import silk.core.option { Option }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.text.string { String }
// A transport that answers from memory, as a test of a harness would use.
struct Scripted {
commands: List<String>,
next: usize,
answers: List<String>,
}
impl Transport for Scripted {
effect fn receive(self: &mut Self) -> Option<String>
! TransportError | OutOfMemoryError
? &mut Transport | &mut Allocator {
if self.next == self.commands.length() {
return Option<String>.None
}
self.next = self.next + 1
return Option<String>.Some {
value: run String.copy(self.commands.asSlice()[self.next - 1].view()),
}
}
effect fn send(self: &mut Self, line: string) -> ()
! TransportError | OutOfMemoryError
? &mut Transport | &mut Allocator {
return run self.answers.append(run String.copy(line))
}
}
// Echoes every command back until the input ends.
effect fn echo() -> ()
! TransportError | OutOfMemoryError
? &mut Transport | &mut Allocator {
let mut more = true
while more {
match move run Transport.receive() {
Option<String>.Some { value } => {
run Transport.send(value.view())
}
Option<String>.None => {
more = false
}
}
}
}
effect fn check() -> i32 ! TransportError | OutOfMemoryError ? &mut Allocator {
let mut scripted = Scripted {
commands: List<String>.make(),
next: 0,
answers: List<String>.make(),
}
run scripted.commands.append(run String.copy("list"))
run scripted.commands.append(run String.copy("quit"))
run echo() |> Effect.provideMut<Transport>(&mut scripted)
if scripted.answers.length() != 2 || scripted.answers.asSlice()[1].view() != "quit" {
return 1
}
return 0
}
effect fn failed(error: TransportError | 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 Transport with import silk.bench.transport { Transport }.
Public declarations: 3.
TransportError#
pub struct TransportErrorA line that could not be carried.
Field message#
pub message: StringWhat went wrong, as one line.
Implementation Debug for TransportError#
impl Debug for TransportErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterTransport#
pub service TransportWhat carries the lines of the driven protocol to the other side and back.
Operation receive#
effect fn receive() -> Option<String>
! TransportError | OutOfMemoryError
? &mut Transport | &mut AllocatorReturns the next line from the other side, without its line end, or nothing when the other side has ended.
Errors#
TransportErrorif the line cannot be read.OutOfMemoryErrorif theAllocatorcannot supply the line.
Operation send#
effect fn send(line: string) -> ()
! TransportError | OutOfMemoryError
? &mut Transport | &mut AllocatorGives line, which holds no line end, to the other side.
Errors#
TransportErrorif the line cannot be written.OutOfMemoryErrorif theAllocatorcannot supply working memory.
StreamTransport#
pub struct StreamTransportA transport over two descriptors: lines are read from one and written to the other.
Details#
Both descriptors may be blocking or nonblocking: an operation waits until the descriptor is ready. The transport does not close them.
Implementation StreamTransport#
impl StreamTransportAssociated function standard#
pub fn standard() -> StreamTransportReturns a transport over standard input and standard output: what a harness uses.
Associated function over#
pub fn over(reads: i32, writes: i32) -> StreamTransportReturns a transport that reads lines from the descriptor reads and writes lines to the
descriptor writes.
Implementation Transport for StreamTransport#
impl Transport for StreamTransportOperation receive#
effect fn receive(self: &mut Self) -> Option<String>
! TransportError | OutOfMemoryError
? &mut Transport | &mut AllocatorOperation send#
effect fn send(self: &mut Self, line: string) -> ()
! TransportError | OutOfMemoryError
? &mut Transport | &mut AllocatorCategory: 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.