silk.bench.process.

Runs one program to its end and measures it: the time it took, the processor time it used, and its peak memory.

When to use#

silk.bench.bench uses Process.time for every sample of a command suite. Use it directly to time a program in a harness of your own.

Details#

Process.time starts the program, waits for it, and reads what the system counted for it with wait4: processor time in user and kernel mode, and peak resident memory, over the program and the children it waited for. The time from start to exit is read from the MonotonicClock. The program's standard input, output and error are closed off, so printing costs it nothing and does not reach the terminal.

Process.perform runs a program for its effect, such as a hook that clears a cache: the program shares the terminal, and a failure is an error.

Both give the program the environment of this process and then the variables of the Launch.

Gotchas#

  • Processes can be measured on Linux with GNU libc and on macOS. On other systems Process.supported is false and both functions fail.

  • Only Linux can limit a program to a number of processors.

Import as Process with import silk.bench.process { Process }.

Public declarations: 4.

Launch#

silk
pub struct Launch

A program ready to start: every path is resolved and every placeholder is filled in.

Field program#

silk
pub program: Path

The program.

Field arguments#

silk
pub arguments: List<String>

The arguments, without the program's own name.

Field directory#

silk
pub directory: Option<Path>

The working directory. Without one, the program starts in the directory of this process.

Field variables#

silk
pub variables: List<Pair>

The environment variables added to those of this process.

Field output#

silk
pub output: Option<Path>

The file that receives the standard output of a timed run, in place of what the file held. Without one, a timed run's output is discarded.

Timed#

silk
pub struct Timed

What one run of a program cost.

Field wall#

silk
pub wall: u64

The time from start to exit, in nanoseconds.

Field user#

silk
pub user: u64

The processor time in user mode, in nanoseconds.

Field system#

silk
pub system: u64

The processor time in kernel mode, in nanoseconds.

Field peak#

silk
pub peak: u64

The peak resident memory, in bytes.

Field exit#

silk
pub exit: i64

The exit status, or -1 when a signal ended the program.

Field signal#

silk
pub signal: i64

The signal that ended the program, or 0.

Field counts#

silk
pub counts: List<Metric>

What the system's counters measured over the run, for a run that asked for them: one value for each counter the system offers, of instructions, cycles, cache-misses, branch-misses and page-faults.

Driven#

silk
pub struct Driven

A program that was started with pipes on its standard input and output, to be driven.

Field pid#

silk
pub pid: i32

The process ID.

Field reads#

silk
pub reads: i32

The descriptor the program's standard output is read from.

Field writes#

silk
pub writes: i32

The descriptor the program's standard input is written to.

Process#

silk
pub struct Process

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

Implementation Process#

silk
impl Process

Associated function supported#

silk
pub fn supported() -> bool

Returns whether this system can measure a process.

Associated function processors#

silk
pub fn processors() -> u32

Returns the number of processors this process may run on, or 0 on a system where Process.time cannot limit them.

Associated function floor#

silk
pub effect fn floor() -> u64
    ? &mut Allocator | &mut FileSystem

Returns the smallest peak memory Process.time can report for a program started now, in bytes, or 0 when there is none.

Details#

On Linux a new process starts with the peak resident memory of the process that started it, so a small program reads as this process's own peak. Other systems count a new process from zero.

Associated function terminal#

silk
pub fn terminal(fd: i32) -> bool

Returns whether the descriptor fd, such as 1 for standard output, is a terminal. It is false on a system where Process.supported is false.

Associated function computer#

silk
pub effect fn computer() -> Environment
    ! OutOfMemoryError
    ? &mut Allocator

Returns the computer this process runs on, for the record of a run, with no recorded environment variables. What the system does not report is unknown or 0.

Errors#

OutOfMemoryError if the Allocator cannot supply the text.

Associated function time#

silk
pub effect fn time(launch: &Launch, cpus: u32, counted: bool) -> Timed
    ! TaskError | OutOfMemoryError
    ? &mut Allocator | &mut MonotonicClock

Runs launch to its end and returns what it cost. With cpus above 0, the program may run only on that many processors, the first ones this process may use.

Details#

A program that exits with a status other than 0, or that a signal ends, is not an error here: the status is in the result, and the caller decides.

With counted, the run also reads the counters of the processor and of the kernel, on Linux on x86_64 and aarch64: instructions, cycles, cache misses, branch misses and page faults, all in user mode, for the program and the processes it starts, not for this process. A counter the system does not offer is left out, so on another system, or where the kernel refuses, counts is empty; a virtual machine often offers only the last.

Errors#

TaskError with status 127 if the program cannot be started, if cpus is more than Process.processors, or if this system cannot measure a process.

Associated function drive#

silk
pub effect fn drive(launch: &Launch, cpus: u32) -> Driven
    ! TaskError | OutOfMemoryError
    ? &mut Allocator

Starts launch with a pipe on its standard input and one on its standard output, and returns at once. With cpus above 0, the program may use only that many processors.

Details#

Both descriptors of the result are nonblocking, as silk.bench.transport.StreamTransport expects. End the program with Process.finish.

Errors#

TaskError with status 127 if the program cannot be started, if cpus is more than Process.processors, or if this system cannot start such a program.

Associated function finish#

silk
pub effect fn finish(driven: &Driven) -> i64
    ! TaskError | OutOfMemoryError
    ? &mut Allocator

Closes the pipes of driven, which ends a program that reads its standard input to the end, waits for the program, and returns its exit status, or -1 when a signal ended it.

Errors#

TaskError with status 127 if the program's exit cannot be collected.

Associated function perform#

silk
pub effect fn perform(launch: &Launch) -> ()
    ! TaskError | OutOfMemoryError
    ? &mut Allocator

Runs launch to its end with the standard streams of this process, for its effect.

Errors#

TaskError if the program cannot be started, exits with a status other than 0, which becomes the error's status, or is ended by a signal.

Associated function text#

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

Returns launch as one line for a reader: the program, then its arguments, separated by spaces. The line is for a report, not for a shell: nothing is quoted.

Errors#

OutOfMemoryError if the Allocator cannot supply the text.

Associated function instructions#

silk
pub fn instructions(profile: &[u8]) -> Option<u64>

Returns the number of instructions a Callgrind output file profile counted: the first number of its summary: line, or of its totals: line when it has no summary. Returns None if profile has neither line or the line has no number.

Examples#

silk
import silk.bench.process { Process }
import silk.core.option { Option }

pub fn main() -> i32 {
  let profile = b"events: Ir\nfn=main\n1 20\ntotals: 1840\nsummary: 1837 12\n"
  if let Option<u64>.Some { value } = Process.instructions(profile) {
    if value == 1837 {
      return 0
    }
  }
  return 1
}

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