Zena
On this page

zena:process

zena
import {…} from 'zena:process';

Spawning and managing host processes from Zena programs.

Provides run and spawn to execute child processes and capture standard output, standard error, execution duration, and exit codes.

Permission Required

Spawning host processes requires running with the --allow-spawn CLI flag or setting ZENA_ALLOW_SPAWN=1 in the environment.

Examples ​

zena
import { run } from 'zena:process';

let result = run(['echo', 'hello']);
if (result.success) {
  let text = result.stdout;
}

Classes

ProcessResult

zena
class ProcessResult

The captured outcome of a finished process.

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
final class Process

A running child process. Both stdout and stderr are captured by the host (there is no streaming in v1); wait() blocks until the process exits and returns the captured outcome. Waiting more than once returns the same result.

Constructors
zena
new(proc: ProcRef)
#
Methods
zena
wait(): ProcessResult
#
zena
waitFor(millis: i64): 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.

Functions

spawnIn

zena
function spawnIn(argv: Array<String>, cwd: String | null, inheritStdio: boolean = false): Process

Start a process without waiting for it. argv[0] is the executable (resolved against PATH by the host); the child inherits the host's environment and, with cwd == null, its working directory. Spawning several processes and waiting on each is how a caller runs work in parallel. A process that cannot be started at all (e.g. the executable does not exist) traps with a descriptive message when waited on.

With inheritStdio, the child reads this process's stdin and writes to its stdout and stderr directly, and nothing is captured.

spawn

zena
function spawn(argv: Array<String>): Process

spawnIn with the host's working directory.

runIn

zena
function runIn(argv: Array<String>, cwd: String | null): ProcessResult

Run a process to completion in the given working directory.

run

zena
function run(argv: Array<String>): ProcessResult

Run a process to completion in the host's working directory.

runInheriting

zena
function runInheriting(argv: Array<String>, cwd: String | null = null): ProcessResult

Runs a process attached to this one's own streams: what it prints appears as it prints it, and it reads this process's stdin. For handing the terminal to another program, where output should interleave live instead of arriving all at once when the child exits.

Nothing is captured, so the result's stdout and stderr are empty; exitCode and wallNanos are set.