Rust · Errors

Errors

use usearch::Error;use usearch::Status;use usearch::*; 3.0.0-rc.1 · 4c3e5023

Every fallible call returns usearch::Result, whose Error carries a Status and a static message, so nothing allocates on the failure path. A failure the binding catches before the call crosses the boundary reports the status the engine would have used.

match index.on(&executor).search(&rows(&query, 4)?, 10, &mut arena) {
    Ok(matches) => println!("{} queries", matches.queries()),
    Err(Error { status: Status::Contended, .. }) => println!("the arena serves another call"),
    Err(error) => println!("{}: {}", error.status, error.message),
}

Status carries the C enumerators’ values and leaves success to Result, so an Error never carries Status::Deferred, which only Deferred::status reports. Status, Mood, Residency, Traversal, DenseMetric and Scalar print through Display and parse through FromStr the names the C tables own, such as "out-of-memory" or "angular", so nothing is compared as a string. A panic inside a predicate, progress handler or value lookup is caught at the C frame, since unwinding out of one is an abort, and resurfaces once the call is final.

API

Types

ResultThe result of every fallible call in this crate.
lib.rs:626 ↗
pub type Result<Value> = Result<Value, Error>;
StructErrorA failure, whether the engine reported it or the binding caught it before the call.
types.rs:612 ↗
pub struct Error

Messages are static storage, so nothing allocates on the failure path.

Fields

statusStatusThe identity of the failure, shared by every binding of the library.
message&'static strThe detail the status alone cannot carry.

Implements

Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, Display, Error
EnumStatusEvery way a call can end besides success, numbered as the library numbers them.
types.rs:523 ↗
pub enum Status

An Error never carries Status::Deferred, which only Deferred::status reports.

Values

Deferred1The call was submitted deferred and is not final yet.
OutOfMemory2An allocation or reservation could not be satisfied.
ShapeMismatch3Dimensionality or row counts disagree.
UnsupportedLayout4A stride or packing the engine cannot traverse.
UnknownKind5A scalar, metric, or residency tag this build does not know.
ReadOnly6A mutating verb on a handle that serves its checkpoint in place.
Io7A file could not be opened, read, written, or parsed.
Device8A device could not be selected, or its memory could not be claimed.
Malformed9A caller-supplied representation could not be decoded.
Internal10The library reported neither success nor a failure.
Overflow11A hard design ceiling was reached, like the 32-bit ID space.
Uninitialized12The verb needs a prior successful reservation that never happened.
ConfigMismatch13The request contradicts an already-frozen configuration.
Contended14The call was refused rather than waited for, like a submission to a full deferred table.
Cancelled15A progress handler stopped the call; what the finished increments leave behind is each verb's own contract.
Unsupported16The verb is declared for every residency but this one does not implement it.
InvalidArgument17An argument breaks the verb's contract.

Implements

Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, Hash, Display, FromStr