Standard Library: std.process
● Intermediate5 min
Every type, method and function of std.process: what the spec lists, then each declaration in its source, with its examples and the line that declares it.
Spec 14.23 · learn it in Running Programs.
A declaration below shows what a program writes against: a type's fields, a function's parameters, what it gives, its contracts (require, ensure) and its examples. kavach test runs every example, so each one is true of the code.
What the spec lists
| Function or method | Gives |
|---|---|
process.run(program, args, folder: "", env: [:]) -> Finished ! ProcessError | Runs program to its end and gives its exit code, what it printed and what it cost |
process.start(program, args, folder: "", env: [:]) -> Child ! ProcessError | Starts program and gives it back running, to read its output as it comes |
child.next() -> Output? | The next line the program printed, waiting for it; none once it has ended and every line was read |
child.each(f) | Calls f(output) with each line as it comes, until f gives false or the program has ended and every line was read |
child.wait() -> Exit | Waits for the program's end, skipping what it still prints |
child.kill() | Ends the program, and every program it started, at once |
process.peak_bytes() -> Int | The most memory this program has held so far, in bytes. Needs no capability |
The results:
| Type | Holds |
|---|---|
Finished | code: Int, out: String, err: String, cpu_ms: Int, peak_bytes: Int; out and err are the lines printed, each ending in a line break |
Output | Out(line: String) or Err(line: String): a line of standard output or of standard error, without its line end |
Exit | code: Int, cpu_ms: Int, peak_bytes: Int |
ProcessError | NotFound(program: String), Denied(program: String) or Failed(reason: String) |
Process can be granted for one program, as Fs is for one folder (8.1):
| Written | Allows |
|---|---|
uses Process | Running any program |
uses Process("verilator") | Only verilator |
std.process · process.kav
use std.process: 5 types and 3 functions. stdlib/process/process.kav
ProcessError type
Why a program couldn't run.
pub type ProcessError = NotFound(program: String) | Denied(program: String) | Failed(reason: String)Output type
A line a program printed, without its line end.
pub type Output = Out(line: String) | Err(line: String)Exit type
How a program ended, and what it and the programs it started cost.
pub type Exit {
pub code: Int
pub cpu_ms: Int
pub peak_bytes: Int
}Finished type
A program run to its end: its exit code, what it printed (each line ending in a line break) and what it cost.
pub type Finished {
pub code: Int
pub out: String
pub err: String
pub cpu_ms: Int
pub peak_bytes: Int
}Child type
A running program. Its tree ends when its last holder ends.
pub type Child: Drop {
id: Int
}next method
The next line the program printed, waiting for it; none once it has ended and every line was read.
pub fn next(self) -> Output? uses Processeach method
Calls f with each line as it comes, until f gives false or the program has ended and every line was read.
pub fn each(self, f: fn(Output) -> Bool) uses Processwait method
Waits for the program's end, skipping what it still prints.
pub fn wait(self) -> Exit uses Processkill method
Ends the program, and every program it started, at once.
pub fn kill(self) uses Processstart function
Starts program with args in folder ("": this program's own), with env added to its environment.
pub fn start(program: String, args: [String], folder: String = "", env: [String: String] = [:]) -> Child ! ProcessError uses Processrun function
Runs program to its end.
pub fn run(program: String, args: [String], folder: String = "", env: [String: String] = [:]) -> Finished ! ProcessError uses Processpeak_bytes function
The most memory this program has held so far, in bytes.
pub fn peak_bytes() -> Int