Enum BackendError 

#[non_exhaustive]
pub enum BackendError {
    DeviceOutOfMemory {
        requested: u64,
        available: u64,
    },
    DeviceLost {
        backend: String,
        device: String,
        generation: u64,
        message: String,
    },
    UnsupportedFeature {
        name: String,
        backend: String,
    },
    PoisonedLock {
        lock_error: String,
    },
    KernelCompileFailed {
        backend: String,
        compiler_message: String,
    },
    DispatchFailed {
        code: Option<i32>,
        message: String,
    },
    Validation {
        source: ValidationError,
    },
    InvalidProgram {
        fix: String,
    },
    CooperativeResidencyExceeded {
        grid_blocks: u64,
        resident_limit: u64,
        detail: String,
    },
    Other(String),
}

Actionable backend dispatch failure.

Every error that flows through the frozen VyreBackend contract must include remediation text beginning with Fix: . This guarantees that conform reports are directly actionable for backend authors and that consumers never receive an opaque failure string.

Use specific variants (DeviceOutOfMemory, KernelCompileFailed, etc.) when the failure class is known. BackendError::Other carries actionable failures that do not fit a structured variant.

Examples

use vyre_driver::BackendError;

let err = BackendError::new("adapter not found. Fix: install a compatible device driver.");
assert!(err.message().contains("Fix:"));

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.

DeviceOutOfMemory

Device ran out of memory during buffer allocation or dispatch.

Fields

requested: u64

Bytes requested that triggered the OOM condition.

available: u64

Bytes reported available at the time of the failure.

DeviceLost

The acquired device generation was lost and all native handles are stale.

Fields

backend: String

Registered backend identifier.

device: String

Backend-local physical or logical device identifier.

generation: u64

Invalidated device generation.

message: String

Concrete device-loss detail.

UnsupportedFeature

The backend does not support a required feature.

Fields

name: String

Feature name (e.g. "subgroup_ops", "f16").

backend: String

Backend identifier (matches crate::backend::VyreBackend::id).

PoisonedLock

Internal lock poisoning was detected during backend synchronization.

Fields

lock_error: String

Diagnostic details from the poison error.

KernelCompileFailed

GPU kernel-source compilation failed.

“Shader” in the variant name is historical and generalised

• the code applies to any kernel-source compile failure across backends. A 2.0 rename to KernelCompileFailed is tracked in the semver-policy doc.

Fields

backend: String

Backend identifier.

compiler_message: String

Compiler error text or lowered shader / IR excerpt.

DispatchFailed

Command dispatch or GPU queue submission failed.

Fields

code: Option<i32>

Optional backend-specific numeric error code.

message: String

Human-readable failure detail.

Validation

Foundation validation rejected the program with a structured issue.

Fields

source: ValidationError

Structured foundation-owned validation issue.

InvalidProgram

The program is structurally invalid for this backend.

Fields

fix: String

Actionable description, should begin with Fix: .

CooperativeResidencyExceeded

A cooperative whole-grid launch could not be made fully resident: the grid has more blocks than the device can co-schedule for a grid-sync barrier. The orchestrator must fall back (loudly) to a recall-identical non-cooperative path rather than launch a kernel that would deadlock.

Fields

grid_blocks: u64

Blocks the launch geometry requires.

resident_limit: u64

Blocks the device can keep co-resident for this kernel.

detail: String

Which residency bound tripped (thread vs occupancy) and the geometry.

Other(String)

Actionable backend failure without a more specific structured class.

Implementations

impl BackendError

pub fn new(message: impl Into<String>) -> Self

Build an unclassified backend error from a complete actionable message.

The message is preserved verbatim. Callers that can identify the failure class use a structured variant instead.

Examples

use vyre_driver::BackendError;

let err = BackendError::new("queue full. Fix: retry with a smaller dispatch size.");
assert_eq!(err.to_string(), "queue full. Fix: retry with a smaller dispatch size.");

pub fn unsupported_extension( backend: impl Into<String>, extension_kind: &str, debug_identity: &str, ) -> Self

Build an actionable unsupported-extension error for opaque IR payloads.

pub fn poisoned_lock<T>(error: PoisonError<T>) -> Self

Build a structured lock-poisoning error.

This constructor accepts any PoisonError from RwLock operations and returns an actionable error carrying the root poison metadata.

pub fn message(&self) -> String

Human-readable failure message, equivalent to ToString::to_string.

Prefer explicit match on variants or ErrorCode for programmatic error handling; avoid string-parsing this output.

pub fn into_message(self) -> String

Consume this error and return its message string.

Useful in map_err chains that expect String.

pub fn code(&self) -> ErrorCode

Machine-readable error code for programmatic error handling.

Use this to drive retry logic, circuit breakers, and alerting without parsing human-readable message strings.

Trait Implementations

impl Clone for BackendError

fn clone(&self) -> BackendError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BackendError

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

Formats the value using the given formatter.

impl Display for BackendError

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

Formats the value using the given formatter.

impl Eq for BackendError

impl Error for BackendError

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.

impl PartialEq for BackendError

fn eq(&self, other: &BackendError) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for BackendError