Enum Error 

#[non_exhaustive]
pub enum Error {
    Io(Error),
    OutOfMemory,
    OutOfGpuMemory {
        required_bytes: u64,
        available_bytes: u64,
        backend: BackendKind,
    },
    NotSupported(Cow<'static, str>),
    InvalidArgument(Cow<'static, str>),
    InvalidState(&'static str),
    Cancelled,
    Timeout,
    WouldBlock,
    DeviceLost {
        backend: BackendKind,
    },
    UnknownParam {
        backend: BackendKind,
        key: String,
    },
    DeviceMismatch {
        expected: DeviceId,
        actual: DeviceId,
    },
    NoCpuShader,
    ExplicitSyncInAutoMode,
    UserKernelPanic {
        backtrace: String,
    },
    ShaderCompile(String),
    FormatMismatch(String),
    QueueBackendMismatch {
        expected: BackendKind,
        actual: BackendKind,
    },
    Fatal(&'static str),
    FatalBackend(Box<dyn Error + Send + Sync + 'static>),
    Backend(Box<dyn Error + Send + Sync + 'static>),
}

Domain error for every leaf operation in gpu-handle-types.

Downstream crates keep their own domain errors with #[from] into this one — this crate has zero backend-library knowledge (no ffmpeg, no wgpu, no ocl error From impls).

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.

Io(Error)

OutOfMemory

OutOfGpuMemory

Fields

required_bytes: u64

available_bytes: u64

backend: BackendKind

NotSupported(Cow<'static, str>)

InvalidArgument(Cow<'static, str>)

InvalidState(&'static str)

An operation was invoked while the object is in a state that cannot service it — an encoder that was already finished, a flush issued while a deferred-submit frame is still awaiting its submit notification, etc. Distinct from Error::InvalidArgument (the argument is fine; the lifecycle position is wrong) and classified as ErrorKind::Configuration (the caller fixes the call order and retries; the same call from the same state fails identically). Carries a &'static str because every state-machine transition message is a compile-time literal — no formatting.

Cancelled

A deliberate, caller-initiated cancellation — an interrupt-token cancel aborting a blocking read, a dropped wait future, an SDK job abort. Not a failure: the operation stopped because it was asked to. Classified as ErrorKind::Cancelled so upper layers can void it (no retry, no error state, no error-level logging) instead of surfacing it as a fault.

Timeout

WouldBlock

A non-blocking operation has no result available yet — the caller should retry later, nothing has failed. This is the leaf form of the “temporary unavailability” signal a poll/try surface needs: e.g. a browser WebCodecs decoder’s synchronous next-frame call returns it when a frame is in flight but not yet delivered (an async poll surface uses Poll::Pending instead and never produces this). Distinct from Error::Timeout (a wait elapsed) and from Ok(None)/EOF (the stream genuinely ended). Classified ErrorKind::Recoverable.

DeviceLost

The underlying GPU / accelerator device is in an unrecoverable state (Vulkan VK_ERROR_DEVICE_LOST, DXGI DXGI_ERROR_DEVICE_REMOVED, CUDA CUDA_ERROR_LAUNCH_FAILED after a TDR, OpenCL CL_INVALID_COMMAND_QUEUE after a fault, …). Distinct from Error::Timeout (which is recoverable — the wait simply hadn’t completed yet) and from Error::NotSupported (which means the platform never supported the operation). Callers MUST tear down any in-flight work bound to the device and rebuild — same-device retries will fail identically.

Fields

backend: BackendKind

UnknownParam

Fields

backend: BackendKind

key: String

DeviceMismatch

Fields

expected: DeviceId

actual: DeviceId

NoCpuShader

ExplicitSyncInAutoMode

UserKernelPanic

Fields

backtrace: String

ShaderCompile(String)

Shader compilation failed. The string carries the backend-specific diagnostic (naga / NVRTC / clBuildProgram output).

FormatMismatch(String)

Bound output / input format does not match what the pipeline / shader requires.

QueueBackendMismatch

An operation was handed an ExternalQueue whose backend does not match the backend of the processor receiving it.

Fields

expected: BackendKind

actual: BackendKind

Fatal(&'static str)

Unrecoverable internal invariant violation that the caller cannot undo by re-configuring — e.g. saturation of a finite counter the crate cannot recycle. Distinct from Error::DeviceLost (which is driver-level) and from Error::NotSupported (which can be fixed by rebuilding with different features). Always classified as ErrorKind::Fatal.

FatalBackend(Box<dyn Error + Send + Sync + 'static>)

A fatal backend error that carries its full diagnostic — the SDK / backend message (and its source() chain), preserved rather than collapsed to a static category string. Downstream crates lower their own fatal domain errors here (a decoder or SDK fault that is not a device-loss) so the exact SDK message propagates all the way to the caller / log instead of a generic “backend fatal error”. Boxed to keep the leaf enum pointer-sized. Classified as ErrorKind::Fatal — same abort contract as Error::Fatal, but with the detail retained.

Backend(Box<dyn Error + Send + Sync + 'static>)

Decoder / encoder / resampler / muxer backend error raised by a downstream media crate. Boxed so the leaf-crate Error stays a small pointer-sized enum, and so a backend can layer its own error enum underneath without pulling SDK-specific From impls into the leaf crate.

Classified as ErrorKind::Recoverable by default. Backends that have richer classification of their own should expose a kind() accessor through their own type and consume the leaf variant only at the outermost boundary.

Implementations

impl Error

pub fn kind(&self) -> ErrorKind

Classify this error. See ErrorKind.

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.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.