# Errors

> UForm for Rust

Every fallible call returns `uform::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 library would have used.

```rust
match model.on(&executor).text_encode(&texts, Outputs::EMBEDDINGS, Scalar::F32, &mut arena) {
    Ok(encoded) => println!("{} items", encoded.embeddings.map_or(0, |rows| rows.count())),
    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`, `Scalar`, `Mood`, `CPUClass`, `GPUClass`, `Modality`, `Objective` and `Negatives` print through `Display` and parse through `FromStr` the names the C tables own, such as `"shape-mismatch"` or `"intel-haswell"`, and `MultimemTier` prints its own, which C never reads back.
A panic inside a progress handler is caught at the C frame, since unwinding out of one is an abort, and resurfaces once the call is final.

`use uform::Error;`

`use uform::Status;`

`use uform::*;`

## Result

The result of every fallible call in this crate.

```rust
pub type Result<Value> = Result<Value, Error>;
```

## Error

A failure, whether the library reported it or the binding caught it before the call.

```rust
pub struct Error
```

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

Mirrors a failed `uform_outcome_t`.

- `status` `Status`: The identity of the failure, shared with the C interface.
- `message` `&'static str`: The detail the status alone cannot carry.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Display`, [`Error`](#Error)

## Status

Every value the C status word takes besides success, numbered alike.

```rust
pub enum Status
```

An [`Error`](#Error) never carries [`Status::Deferred`](#Deferred), which only [`Deferred::status`](https://www.unum.cloud/docs/uform/rust/receivers-and-deferred-calls.md#status) reports.

Mirrors `uform_status_t`.

- `Deferred` = `1`: The call was submitted deferred and is not final yet.
- `OutOfMemory` = `2`: Device, pinned, or host memory could not be allocated, or the executor's scratch ceiling
is too low.
- `ShapeMismatch` = `3`: Item counts, a pixel shape, or a batch envelope disagree with the call or the model.
- `UnsupportedLayout` = `4`: A stride or packing the model cannot read.
- `UnknownKind` = `5`: A scalar, modality, or name this build does not know.
- `Io` = `7`: A checkpoint file could not be opened, read, or written.
- `Device` = `8`: The driver refused or the device faulted; after a fault the executor refuses
every later call.
- `Malformed` = `9`: Supplied bytes could not be decoded: a checkpoint, an image, a clip, or a recording.
- `Internal` = `10`: The library reported neither success nor a failure.
- `ConfigMismatch` = `13`: The request contradicts a frozen configuration, like resuming a checkpoint
of another geometry.
- `Contended` = `14`: The call was refused rather than waited for, like a submission to a full deferred table.
- `Cancelled` = `15`: A progress handler stopped the call; it unwound and published nothing.
- `Unsupported` = `16`: The verb is declared for every residency or model, but this one does not implement it.
- `InvalidArgument` = `17`: An argument breaks the verb's contract.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Hash`, `Display`, `FromStr`