emblema_hal/error.rs
1//! Error types shared across every backend.
2
3use thiserror::Error;
4
5/// Result alias used throughout the HAL.
6pub type Result<T, E = Error> = std::result::Result<T, E>;
7
8#[derive(Debug, Error)]
9pub enum Error {
10 /// The backend or driver does not support the requested operation.
11 ///
12 /// Callers are expected to have checked [`crate::Capabilities`] first;
13 /// receiving this is a bug in the caller, not a condition to branch on at
14 /// the call site.
15 #[error("unsupported by this backend: {0}")]
16 Unsupported(&'static str),
17
18 /// Device memory or host memory exhausted.
19 #[error("out of memory allocating {what}")]
20 OutOfMemory { what: &'static str },
21
22 /// A requested resource exceeded a reported device limit.
23 #[error("{what} of {requested} exceeds device limit of {limit}")]
24 LimitExceeded {
25 what: &'static str,
26 requested: u64,
27 limit: u64,
28 },
29
30 /// A dma-buf could not be imported, usually a format or modifier the
31 /// importing device does not accept.
32 #[error("failed to import external image: {0}")]
33 ExternalImport(String),
34
35 /// The device was lost. Everything created from it is invalid.
36 #[error("device lost")]
37 DeviceLost,
38
39 /// A wait exceeded its timeout without what it waited for happening.
40 ///
41 /// `what` names it, because a frame loop has more than one thing it can be
42 /// stuck on -- a fence that never signals, a flip that never lands, a slot
43 /// that never comes free -- and they have different causes. A single
44 /// message for all of them means reading the code and reasoning about
45 /// which timeout could have elapsed in the time the run took, which is what
46 /// this error made necessary once.
47 #[error("timed out waiting for {what}")]
48 Timeout { what: &'static str },
49
50 /// Backend-specific failure that has no portable representation.
51 #[error("{backend} error: {detail}")]
52 Backend {
53 backend: &'static str,
54 detail: String,
55 },
56}