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:

TEXT
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     quit
  • list asks 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, as silk.bench.lines describes them. It may send configuration lines such as check: 9f2c41aa before the result line.

  • quit ends 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#

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

silk
pub struct TransportError

A line that could not be carried.

Field message#

silk
pub message: String

What went wrong, as one line.

Implementation Debug for TransportError#

silk
impl Debug for TransportError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Transport#

silk
pub service Transport

What carries the lines of the driven protocol to the other side and back.

Operation receive#

silk
effect fn receive() -> Option<String>
    ! TransportError | OutOfMemoryError
    ? &mut Transport | &mut Allocator

Returns the next line from the other side, without its line end, or nothing when the other side has ended.

Errors#

  • TransportError if the line cannot be read.

  • OutOfMemoryError if the Allocator cannot supply the line.

Operation send#

silk
effect fn send(line: string) -> ()
    ! TransportError | OutOfMemoryError
    ? &mut Transport | &mut Allocator

Gives line, which holds no line end, to the other side.

Errors#

  • TransportError if the line cannot be written.

  • OutOfMemoryError if the Allocator cannot supply working memory.

StreamTransport#

silk
pub struct StreamTransport

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

silk
impl StreamTransport

Associated function standard#

silk
pub fn standard() -> StreamTransport

Returns a transport over standard input and standard output: what a harness uses.

Associated function over#

silk
pub fn over(reads: i32, writes: i32) -> StreamTransport

Returns a transport that reads lines from the descriptor reads and writes lines to the descriptor writes.

Implementation Transport for StreamTransport#

silk
impl Transport for StreamTransport

Operation receive#

silk
effect fn receive(self: &mut Self) -> Option<String>
    ! TransportError | OutOfMemoryError
    ? &mut Transport | &mut Allocator

Operation send#

silk
effect fn send(self: &mut Self, line: string) -> ()
    ! TransportError | OutOfMemoryError
    ? &mut Transport | &mut Allocator

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