Struct ExecuteOptions 

pub struct ExecuteOptions {
    pub vars: HashMap<String, Value>,
    pub timeout: Option<Duration>,
    pub cancel_token: Option<CancellationToken>,
    pub cwd: Option<PathBuf>,
    pub traceparent: Option<String>,
    pub tracestate: Option<String>,
    pub baggage: BTreeMap<String, String>,
    pub stdin: Option<Vec<u8>>,
    pub interrupt: Option<Arc<dyn Fn() -> bool + Sync + Send>>,
}

Per-call options for Kernel::execute_with_options.

Construct with ExecuteOptions::new() and the chainable with_* builders, or via Default.

Cancellation vs. timeout — embedder note

If a cancel_token is supplied, it is raced against the kernel’s internal token. The kernel does NOT cancel the embedder’s token on its own timeouts — it cancels its internal token and returns exit code 124. So your_token.is_cancelled() after the call returns reflects only whether you (or someone sharing your token) cancelled, not whether the kernel timed out. Distinguish via the returned ExecResult.code: 124 = kernel timeout, 130 = cancellation (Ctrl-C / Kernel::cancel).

Fields

vars: HashMap<String, Value>

Variables exported into this call’s environment (per-call overlay).

timeout: Option<Duration>

Per-call timeout. Overrides KernelConfig::request_timeout.

None means no timeout (or whatever the kernel-config default is). Some(Duration::ZERO) returns exit 124 immediately without spawning anything — useful for tests and dry-run paths. Any other Some(d) lets the kernel run for at most d before cancelling (which kills external children with the configured grace) and returning 124.

cancel_token: Option<CancellationToken>

Optional externally-owned cancellation token, raced against the kernel’s internal token. Either firing cancels the request and kills any running external children. The kernel does not store this token in its own state — it’s a per-call read-only input, so embedders are free to drop or reuse the original token after the call returns. CancellationToken is internally Arc-shared, so clone() it into the builder if you want to keep your original handle.

cwd: Option<PathBuf>

Per-call working directory override.

When Some(path), the kernel runs this call as if cd path happened first, then restores the prior cwd on return. Useful for embedders that run scripts in workspace contexts (notebook cells, per-tool dirs) without polluting the long-lived kernel’s cwd.

traceparent: Option<String>

W3C traceparent of the embedder’s active span, e.g. "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01". When set, the kernel’s execution span parents onto it, so kaish’s spans appear as children of the embedder’s trace rather than as orphan roots.

tracestate: Option<String>

W3C tracestate (vendor-specific list) that rides alongside traceparent. Per the W3C spec, tracestate is meaningless without a traceparent, so the kernel ignores it unless traceparent is also set.

baggage: BTreeMap<String, String>

W3C baggage — cross-cutting identifiers (owner, connection, tenant, …) the embedder wants stamped onto the trace. Propagated to every child span. Independent of traceparent: baggage with no trace context starts a fresh root that still carries the identifiers.

stdin: Option<Vec<u8>>

Standard input for this call, seeded to the first top-level command that reads stdin. A command that consumes less than the whole buffer (read, a pipeline stage that never reads stdin) leaves the remainder for the next statement in the same call — it is not drained wholesale to the first reader.

Lets a non-interactive frontend feed piped input, e.g. printf '…' | kaish -c 'sort'. Without it a bare top-level builtin reading stdin has no input source and silently produces nothing. Bytes-typed (GH #176) to match ExecContext::set_stdin: a byte-aware builtin (wc -c, cat, cmp, checksum, …) sees binary content exactly, while a text-only builtin (grep, sed, …) still refuses it loudly at the point it asks for text (read_stdin_to_text), not here. Embedders that already hold a complete buffer use this; one that wants to avoid pre-draining an open process stdin should prefer Kernel::execute_with_pipe_stdin instead.

interrupt: Option<Arc<dyn Fn() -> bool + Sync + Send>>

Polled interrupt check, for embedders whose thread cannot fire cancel_token while execution runs — the motivating case is single-threaded wasm, where the browser’s main thread flips a SharedArrayBuffer flag and this closure reads it. The kernel polls at its cancellation checkpoints (each loop iteration, among others) and, on true, fires its internal cancel — the same exit-130 path as Kernel::cancel(). Keep the closure cheap: it runs on the hot path. None (the default) polls nothing.

Implementations

impl ExecuteOptions

pub fn new() -> ExecuteOptions

pub fn with_vars(self, vars: HashMap<String, Value>) -> ExecuteOptions

Replace the entire vars overlay with the given map.

pub fn with_var(self, name: impl Into<String>, value: Value) -> ExecuteOptions

Add a single variable to the overlay (extending; last write wins).

pub fn with_interrupt( self, check: Arc<dyn Fn() -> bool + Sync + Send>, ) -> ExecuteOptions

Install a polled interrupt check (see the interrupt field).

pub fn with_timeout(self, timeout: Duration) -> ExecuteOptions

pub fn with_cancel_token(self, token: CancellationToken) -> ExecuteOptions

pub fn with_cwd(self, cwd: PathBuf) -> ExecuteOptions

Run this call as if cd path had happened first; the prior cwd is restored on return.

pub fn with_traceparent(self, traceparent: impl Into<String>) -> ExecuteOptions

Set the W3C traceparent the kernel’s execution span should parent onto.

pub fn with_tracestate(self, tracestate: impl Into<String>) -> ExecuteOptions

Set the W3C tracestate that rides alongside traceparent. Ignored by the kernel unless a traceparent is also present.

pub fn with_baggage(self, baggage: BTreeMap<String, String>) -> ExecuteOptions

Replace the entire baggage map with the given identifiers.

pub fn with_baggage_entry( self, key: impl Into<String>, value: impl Into<String>, ) -> ExecuteOptions

Add a single baggage identifier (extending; last write wins).

pub fn with_stdin(self, stdin: impl Into<Vec<u8>>) -> ExecuteOptions

Set the standard input fed to this call, starting with the first stdin-reading command; whatever a command doesn’t consume carries forward to the next one in the same call.

Accepts anything Into<Vec<u8>> — a &str/String (the common text case) or a raw Vec<u8> (binary, GH #176) both work.

Trait Implementations

impl Clone for ExecuteOptions

fn clone(&self) -> ExecuteOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for ExecuteOptions

fn default() -> ExecuteOptions

Returns the “default value” for a type.