Enum BackendError 

#[non_exhaustive]
pub enum BackendError {
    DeviceOutOfMemory {
        requested: u64,
        available: u64,
    },
    UnsupportedFeature {
        name: String,
        backend: String,
    },
    PoisonedLock {
        lock_error: String,
    },
    KernelCompileFailed {
        backend: String,
        compiler_message: String,
    },
    DispatchFailed {
        code: Option<i32>,
        message: String,
    },
    InvalidProgram {
        fix: String,
    },
    CooperativeResidencyExceeded {
        grid_blocks: u64,
        resident_limit: u64,
        detail: String,
    },
    Raw(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.

Prefer specific variants (DeviceOutOfMemory, KernelCompileFailed, etc.) over BackendError::new in new backends. The Raw variant exists solely for backward compatibility with existing call sites.

Examples

use vyre::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.

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.

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.

Raw(String)

Fallback for backends that have not migrated to structured errors.

New backends should use a specific variant. This variant exists solely to preserve backward compatibility with BackendError::new.

Implementations

impl BackendError

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

Build a fallback BackendError::Raw after verifying the message is actionable.

If the supplied message already contains a Fix: section it is used verbatim. Otherwise a generic fallback hint is appended. Prefer specific variants (DeviceOutOfMemory, KernelCompileFailed, etc.) over this constructor in new code.

Examples

use vyre::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 From<Error> for BackendError

fn from(error: Error) -> Self

Converts to this type from the input type.

impl PartialEq for BackendError

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for BackendError