Struct Subprocess 

pub struct Subprocess { /* private fields */ }

Runs each trial as a child process, feeding it sampled parameters.

A Subprocess is a plain Objective: build one from a search space and a CommandTemplate, set the policies you need (a timeout, a prune_exit_code, export_params, a working_dir), and drive it with run (the ergonomic path, which also sets ENV_STUDY) or with Study::optimize_with directly. Parallelism, retries and budgets come from the Study; the executor contributes the process, the substitution, and the result protocol.

See the module documentation for the template/environment channels, the result protocol, the trust model, and how determinism and resume are preserved.

Implementations

impl Subprocess

pub fn new(schema: SpaceSchema, template: CommandTemplate) -> Result<Self>

Builds an executor for schema, launching template per trial.

Every {name} the template references must be a parameter the schema declares; this is checked once, here, so a typo is caught before the first trial rather than failing all of them.

The defaults are: no timeout, PRUNE_EXIT_CODE, parameters not exported to the environment, and the parent’s working directory.

The study must declare the same space

Each trial resolves its parameters through TrialCtx::suggest_declared, which reads the range from the study’s ask-time space, not from schema — schema here only validates template and lists which names to ask for. This constructor cannot check that the eventual study declares the same parameters: no Study exists yet. run does check, before the first trial, and returns Error::InvalidSpace naming whichever parameter is missing, rather than every trial separately failing with Error::UnknownParam. Build the study with .with_space(schema.clone()), as the module example does, to satisfy it.

Errors

Error::InvalidSpace if the template references a parameter the schema does not declare.

pub const fn timeout(self, timeout: Duration) -> Self

Kills a child that has not finished within timeout and fails the trial.

pub const fn prune_exit_code(self, code: i32) -> Self

Sets the exit code that means “prune this trial” (default PRUNE_EXIT_CODE).

pub fn export_params(self, prefix: impl Into<String>) -> Self

Also exports each sampled parameter as an environment variable.

A parameter lr becomes <prefix>lr. Pass DEFAULT_PARAM_PREFIX for the conventional ATUNE_PARAM_ prefix. The prefix must be non-empty and cannot contain = or NUL (see the trust model); invalid exported keys are rejected when the executor runs.

pub fn env(self, key: impl Into<OsString>, value: impl Into<OsString>) -> Self

Sets a fixed environment variable on every child.

For configuration the program needs but the search does not tune — CUDA_VISIBLE_DEVICES, PYTHONPATH, a dataset path. These are applied on top of the inherited environment and before the framework’s ATUNE_* variables and any exported parameters, so a fixed variable never shadows the handshake.

pub fn deadline_env(self, key: impl Into<OsString>) -> Self

Passes the remaining outer timeout to each child through key.

The value is computed immediately before spawn, after sampling and command rendering, so a nested worker cannot restart the full timeout budget. The key is intentionally generic; integrations can define their own wire name without coupling atune_core to a sibling crate.

pub fn envs<I, K, V>(self, vars: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: Into<OsString>, V: Into<OsString>,

Sets several fixed environment variables on every child.

As env, for a batch.

pub fn working_dir(self, dir: impl Into<PathBuf>) -> Self

Runs each child in dir instead of inheriting the parent’s directory.

pub const fn capture_limit(self, bytes: usize) -> Self

Retains at most bytes of each stream (default 64 KiB).

bytes must lie in 1..=MAX_OUTPUT_CAPTURE_LIMIT. Like prune_exit_code the value is checked when the executor is used rather than here, so the builder stays infallible and const; run and evaluate return Error::InvalidSpace for an out-of-range bound instead of quietly capturing without a limit.

pub fn run(&self, study: &Study) -> Result<()>

Optimizes study by running each trial as a child process.

A thin wrapper over Study::optimize_with: it sets ENV_STUDY on every child (the one identifier only the study knows) and otherwise leans entirely on the study loop, so parallelism, the RetryPolicy, budgets and resume behave exactly as for an in-process objective.

Before the first trial, checks that study’s own declared space carries every parameter this executor’s schema names — the precondition new documents (see its “The study must declare the same space” section) but cannot itself check, since no Study exists yet. This is the same reasoning new’s own template check already gives for validating early: “a typo is caught before the first trial rather than failing all of them”.

Errors

Error::InvalidSpace if study’s declared space is missing a parameter this executor names; otherwise whatever Study::optimize_with returns: the first fatal storage/sampler fault, or Error::Conflict if the study asked for parallelism > 1 without the system feature. A failing child is not an error here — it is recorded as a failed trial and the run continues.

Trait Implementations

impl Clone for Subprocess

fn clone(&self) -> Subprocess

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Subprocess

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Objective for Subprocess

fn evaluate(&self, ctx: &mut TrialCtx<'_>) -> Result<Outcome>

Runs one trial as a child process.

ENV_STUDY is not set on this path — use Subprocess::run for that; the trial id in ENV_TRIAL already identifies the trial in storage.