LibTmux.Transport

Description#

Bounded child processes

Executor accepts a nonempty positional argv of defined, NUL-free strings. It invokes that executable directly. Shell syntax, tmux command syntax and FORMAT expansion belong to callers above this layer.

execute returns a Result. execute-async always returns a Promise, including for invalid arguments or closed admission. Each call copies argv, environment entries and input bytes before asynchronous work begins. An omitted environment copies the current environment; an explicit empty mapping passes no variables. Input is a Blob, and the child receives EOF after those bytes are written. Both output streams are binary and drain concurrently.

timeout-ms bounds an admitted operation, max-output-bytes bounds combined retained stdout/stderr, and cleanup-timeout-ms bounds waiting after forced termination. Their defaults are 10000 ms, 8388608 bytes and 1000 ms. All are positive integers. Encoded tmux command size has a separate Engine policy. execute and execute-async accept an optional timeout-ms override for callers sharing one deadline across several child operations.

By default a nonzero exit or signal throws X::LibTmux::Command. :!check returns its Result with outcome Failed instead. Spawn failure, invalid input, timeout, cancellation, output overflow and I/O failures still throw. Error records retain bounded output bytes, process identity and reaping evidence. NotStarted means no child effects were admitted. Failed and Indeterminate do not mean that earlier effects were rolled back. Complete means child process completion, not completion of a program controlled through tmux.

Cancellation is one shot. Dropping an operation Promise does not cancel its child. Explicit cancellation and executor close terminate admitted children; close callers share one Promise. A close failure remains observable on later close calls. The executor owns direct child clients, not programs deliberately started in a tmux pane or arbitrary descendant daemons. Executor and Cancellation cannot be cloned. Result clones reconstruct and validate replacement attributes, copying output bytes again.