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.supportedis 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#
pub struct LaunchA program ready to start: every path is resolved and every placeholder is filled in.
Field program#
pub program: PathThe program.
Field arguments#
pub arguments: List<String>The arguments, without the program's own name.
Field directory#
pub directory: Option<Path>The working directory. Without one, the program starts in the directory of this process.
Field variables#
pub variables: List<Pair>The environment variables added to those of this process.
Field output#
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#
pub struct TimedWhat one run of a program cost.
Field wall#
pub wall: u64The time from start to exit, in nanoseconds.
Field user#
pub user: u64The processor time in user mode, in nanoseconds.
Field system#
pub system: u64The processor time in kernel mode, in nanoseconds.
Field peak#
pub peak: u64The peak resident memory, in bytes.
Field exit#
pub exit: i64The exit status, or -1 when a signal ended the program.
Field signal#
pub signal: i64The signal that ended the program, or 0.
Field counts#
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#
pub struct DrivenA program that was started with pipes on its standard input and output, to be driven.
Field pid#
pub pid: i32The process ID.
Field reads#
pub reads: i32The descriptor the program's standard output is read from.
Field writes#
pub writes: i32The descriptor the program's standard input is written to.
Process#
pub struct ProcessThe owner type of the process functions. It has no fields and is never constructed.
Implementation Process#
impl ProcessAssociated function supported#
pub fn supported() -> boolReturns whether this system can measure a process.
Associated function processors#
pub fn processors() -> u32Returns the number of processors this process may run on, or 0 on a system where
Process.time cannot limit them.
Associated function floor#
pub effect fn floor() -> u64
? &mut Allocator | &mut FileSystemReturns 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#
pub fn terminal(fd: i32) -> boolReturns 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#
pub effect fn computer() -> Environment
! OutOfMemoryError
? &mut AllocatorReturns 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#
pub effect fn time(launch: &Launch, cpus: u32, counted: bool) -> Timed
! TaskError | OutOfMemoryError
? &mut Allocator | &mut MonotonicClockRuns 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#
pub effect fn drive(launch: &Launch, cpus: u32) -> Driven
! TaskError | OutOfMemoryError
? &mut AllocatorStarts 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#
pub effect fn finish(driven: &Driven) -> i64
! TaskError | OutOfMemoryError
? &mut AllocatorCloses 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#
pub effect fn perform(launch: &Launch) -> ()
! TaskError | OutOfMemoryError
? &mut AllocatorRuns 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#
pub effect fn text(launch: &Launch) -> String
! OutOfMemoryError
? &mut AllocatorReturns 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#
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#
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.