Cmd

Thirty seconds.

Long enough for a real encode of a short clip, short enough that a task parked on a program that will never answer is eventually collected. A command that genuinely takes longer says so with with_timeout_ms.

Eight megabytes, applied to each captured stream on its own.

The same figure Http caps a response body at, for the same reason: it holds a large text or JSON payload and not an accidental video.

A command to run program with no arguments.

Every bound is set here, so there is no way to build a command without a deadline or without output limits. program is looked up on this process's PATH when it contains no path separator, and used as a path when it does.

Append one argument, exactly as the child will see it.

Append several arguments, in order.

Set one environment variable for the child.

A name that is empty, or that contains = or a NUL, cannot be set on any operating system this platform runs on, and fails the run with SpawnFailed rather than being dropped silently.

Set several environment variables for the child.

Whether to drop this process's environment before applying with_env.

Bool.True gives the child only what the command names, which is what a reproducible invocation of a tool wants. It does not remove the child's other inheritances: the working directory, the user account and the open standard streams are unchanged.

Run the child in this directory instead of this process's own.

Only the child moves; nothing changes the working directory of the application itself, so a path this app uses afterwards still resolves the way every other path in it does. A relative program is still resolved against this process's directory, not against this one.

How long to wait for the child before killing it.

The deadline covers the whole run, and 0 is normalized to 1: there is no way to ask for no deadline, because a task parked forever on a program that never exits is a leak the app cannot see.

The most standard output to capture, in bytes.

A child that writes more fails the run with StdoutLimitExceeded rather than handing back a prefix. The host clamps this to sixty-four megabytes, so asking for more than it will hold gets that figure and the refusal arrives there instead.

The most standard error to capture, in bytes. StderrLimitExceeded otherwise, on the same terms as with_stdout_limit.

Run the command and wait for the child to finish.

At most eight children run at once. The slot is taken before anything is started and released when the child has been reaped, so a Busy means precisely that no process was created. Bounding what is started is what keeps a task per child from becoming a process per task.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!.

update! = |model, input| {
    if input.devices.key_pressed(KeyE) {
        Task.spawn!(
            input,
            || match Cmd.run!(Cmd.new("git").with_args(["rev-parse", "HEAD"])) {
                Ok(output) => Revision(Str.from_utf8_lossy(output.stdout))
                Err(err) => RevisionFailed(err)
            },
        )
    }
    Ok(model)
}

Run the command and read both streams as text.

The decoding is lossy: bytes that are not valid UTF-8 become the replacement character rather than failing the run, because a tool that puts one stray byte in a progress line has still told the app what it needed to know. Use run! when a stream has to survive exactly.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!.