zena:process
zena
import {…} from 'zena:process';
Spawning host processes, for programs the zena command's host runs:
zena-cli:host/process as the compiler synthesizes it from the
host's WIT. The host grants it to the command and to zena-run --allow-spawn; anywhere else the imports are stubs that trap.
Examples
zena
import { run } from 'zena:process';
let result = await run(['git', 'status']);
if (result.succeeded()) {
console.log(result.stdout);
}
Classes
ProcessResult
zena
class ProcessResult
How a process ended, and what it wrote.
Constructors
zena
new()
Properties
zena
exitCode: i32
zena
stdout: String
zena
stderr: String
zena
wallNanos: i64
Wall-clock nanoseconds from spawn to exit.
zena
timedOut: boolean
True when the process overran a waitFor deadline and was killed
rather than exiting on its own. Whatever it had written before the
deadline is still in stdout/stderr.
Methods
zena
succeeded(): boolean
Process
zena
resource class Process extends Resource
A running process: a resource over the host's handle, held as
Own<Process> and released when the owner leaves scope. Releasing
it does not end the process; it lets go of the host's record of it.
Constructors
zena
new(proc: Own<HostProcess>)
Methods
zena
async wait(): Future<ProcessResult>
Waits for the process to exit without blocking this program's other tasks.
zena
async waitFor(millis: i64): Future<ProcessResult>
Waits at most millis for the process to exit, killing it if it
overruns — the result then has timedOut set, and holds whatever
it managed to write first. A non-positive millis waits forever,
so a caller can disable its timeout without branching. Waiting
again returns the same result.
zena
hasExited(): boolean
Whether the process has already exited.
zena
async readLine(): Future<String | null>
Reads the next line written to stdout or stderr (without its \n or
\r\n), or null once both streams close. Returns null immediately
when stdio is inherited. Lines read here are still included in the
final ProcessResult.
zena
async stop(graceMillis: i64 = 2000): Future<ProcessResult>
Asks the process to stop (SIGTERM on Unix, sent to its process group
when started with processGroup: true), waits up to graceMillis
for it to exit, and force-kills it if it is still running.
Type aliases
SpawnOptions
zena
type SpawnOptions = {cwd?: String, inheritStdio?: boolean, processGroup?: boolean, input?: String, env?: Array<(String, String)>, envRemove?: Array<String>}
How to start a process. Every field may be left out.
Functions
spawnWith
zena
function spawnWith(argv: Array<String>, options: SpawnOptions): Own<Process>
The working directory, in this program's view of the file system; this program's own if absent.
Connect the process to this program's own stdin, stdout and stderr, so what it writes appears as it writes it. Its output is captured into the result if absent.
Start the process in a new process group of its own on Unix, so
stop and timeouts reach any child processes it spawns too.
Written to the process's stdin, which is then closed. The process reads end of input straight away if absent.
Environment variables to set in the process, which otherwise inherits this program's host's environment.
Environment variables to leave out of the process's environment.
Start a process from an argument vector, the program first.
zena
let sorted = await runWith(['sort'], {input: 'b\na\n'});
runWith
zena
async function runWith(argv: Array<String>, options: SpawnOptions): Future<ProcessResult>
Runs a process to completion; see spawnWith.
spawnIn
zena
function spawnIn(argv: Array<String>, cwd: String | null, inheritStdio: boolean = false): Own<Process>
Start a process from an argument vector, the program first, in the
directory cwd (this program's own when null). With inheritStdio
the process writes to this program's own streams instead of having
its output captured.
spawn
zena
function spawn(argv: Array<String>): Own<Process>
runIn
zena
async function runIn(argv: Array<String>, cwd: String | null): Future<ProcessResult>
run
zena
async function run(argv: Array<String>): Future<ProcessResult>
runInheriting
zena
async function runInheriting(argv: Array<String>, cwd: String | null = null): Future<ProcessResult>
Run a process connected to this program's own stdio, so its output
appears as it is written; the result's stdout and stderr are
empty.