Enum Error 

#[non_exhaustive]
pub enum Error {
    TrialPruned,
    TrialPaused,
    Incompatible {
        param: String,
        reason: String,
    },
    UnknownParam(String),
    OutOfRange {
        param: String,
        detail: String,
    },
    InvalidSpace(String),
    SpaceExhausted,
    LostRace,
    Backpressure(String),
    ResourceLimit {
        resource: String,
        limit: usize,
    },
    Unsupported(String),
    LeaseLost,
    Conflict(String),
    NotFound(String),
    Storage(String),
    Sampler(String),
    Scheduler(String),
    Objective(Box<dyn Error + Send + Sync>),
}

Everything that can go wrong inside atune.

The type is fully owned (no borrowed lifetimes) and Send + Sync, so it can cross thread and process boundaries, be stored in a trial record, and be boxed into a foreign error chain.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

TrialPruned

The trial was pruned by the scheduler; the objective should stop.

This is the ?-able sentinel described in the module documentation. It signals a decision, not an error: the trial’s last intermediate value becomes its objective value (see FrozenTrial::objective_value).

TrialPaused

The trial was paused by the scheduler; the objective should stop, but the trial is not finished and may be resumed later.

The ?-able sibling of TrialPruned, returned by TrialCtx::report / TrialCtx::should_stop when a scheduler answers Decision::Pause. A trial that ends its evaluation this way is recorded as TrialState::Paused — it keeps its checkpoint reference and can be woken again with Command::ResumeTrial — rather than as a failure or a terminal prune.

Incompatible

A parameter’s distribution is incompatible with the one already recorded for that name in this study.

Numeric bound drift is accepted; a change of categorical choice set, of log scaling, or of distribution kind is rejected — see Distribution::is_compatible_with.

Fields

param: String

The parameter name.

reason: String

Why the two distributions cannot describe the same parameter.

UnknownParam(String)

A parameter name was referenced that the search space does not declare.

OutOfRange

A value falls outside the support of its distribution.

Fields

param: String

The parameter name.

detail: String

What was expected and what was seen.

InvalidSpace(String)

A search space (or a single distribution) is malformed.

Raised by the fallible Distribution constructors: low > high, a non-finite bound, a non-positive step, a logarithmic distribution whose lower bound is not strictly positive, a duplicate parameter name, an empty or duplicated categorical choice set.

SpaceExhausted

A finite search space has no unvisited configuration left.

Returned by exhaustive samplers (Grid) once every point of the cartesian product has been handed out.

LostRace

A concurrent worker won a race for the same resource.

Callers should re-read state and retry rather than fail the study.

Backpressure(String)

A bounded internal buffer is full, so the operation was refused.

This is deliberately not silence: the alternative — dropping the oldest entry to make room — loses the record that lets a finished trial be matched back to the work that produced it, and a search that has quietly stopped learning looks exactly like one that is working. Retrying after outstanding work drains is the intended response.

ResourceLimit

A bounded resource cannot fit the requested operation.

This is distinct from Backpressure: the operation is too large for its configured bound even when no other caller is contending for capacity.

Fields

resource: String

The bounded resource that rejected the operation.

limit: usize

The configured finite limit.

Unsupported(String)

The selected backend does not provide the requested atomic capability.

LeaseLost

An ownership-fenced operation was attempted with a stale owner/epoch token or stale lease observation.

Conflict(String)

The requested operation contradicts durable state.

The canonical case is mutating a finished trial: Complete, Pruned and Failed trials are immutable — see the states a trial moves through.

NotFound(String)

The requested study, trial or state blob does not exist.

Storage(String)

A storage backend failed for a backend-specific reason.

Sampler(String)

A sampler failed to produce a value.

Scheduler(String)

A scheduler failed to reach a decision.

Objective(Box<dyn Error + Send + Sync>)

The user’s objective function failed.

The original error is preserved as the source of the chain so that a failed trial’s record keeps the real cause.

Implementations

impl Error

pub fn objective<E>(source: E) -> Self

where E: Error + Send + Sync + 'static,

Wraps a user error from an objective function.

use atune_core::error::Error;

let io = std::io::Error::other("checkpoint missing");
let err = Error::objective(io);
assert!(matches!(err, Error::Objective(_)));

pub const fn is_pruned(&self) -> bool

Returns true for the Error::TrialPruned sentinel.

Study loops use this to route a pruned trial to TrialState::Pruned instead of TrialState::Failed.

pub const fn is_paused(&self) -> bool

Returns true for the Error::TrialPaused sentinel.

Study loops use this to route a paused trial to TrialState::Paused — a resumable, non-terminal state — instead of TrialState::Failed.

pub const fn is_retryable(&self) -> bool

Returns true if retrying the operation may succeed.

Lost races are always retryable; nothing else is decided here (a retry policy for failed trials is a study-level concern).

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.