wgpu_types/
error.rs

1//! Shared types for WebGPU errors. See also:
2//! <https://gpuweb.github.io/gpuweb/#errors-and-debugging>
3
4use alloc::boxed::Box;
5use alloc::string::String;
6use core::{error, fmt};
7
8/// A classification of WebGPU error for implementers of the WebGPU API to use in their own error
9/// layer(s).
10///
11/// Strongly correlates to the [`GPUError`] and [`GPUErrorFilter`] types in the WebGPU API, with an
12/// additional [`Self::DeviceLost`] variant.
13///
14/// [`GPUError`]: https://gpuweb.github.io/gpuweb/#gpuerror
15/// [`GPUErrorFilter`]: https://gpuweb.github.io/gpuweb/#enumdef-gpuerrorfilter
16#[derive(Clone, Copy, Debug, Eq, PartialEq)]
17#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
18pub enum ErrorType {
19    /// A [`GPUInternalError`].
20    ///
21    /// [`GPUInternalError`]: https://gpuweb.github.io/gpuweb/#gpuinternalerror
22    Internal,
23    /// A [`GPUOutOfMemoryError`].
24    ///
25    /// [`GPUOutOfMemoryError`]: https://gpuweb.github.io/gpuweb/#gpuoutofmemoryerror
26    OutOfMemory,
27    /// A [`GPUValidationError`].
28    ///
29    /// [`GPUValidationError`]: https://gpuweb.github.io/gpuweb/#gpuvalidationerror
30    Validation,
31    /// Indicates that device loss occurred. In JavaScript, this means the [`GPUDevice.lost`]
32    /// property should be `resolve`d.
33    ///
34    /// [`GPUDevice.lost`]: https://www.w3.org/TR/webgpu/#dom-gpudevice-lost
35    DeviceLost,
36}
37
38/// A trait for querying the [`ErrorType`] classification of an error.
39///
40/// This is intended to be used as a convenience by implementations of WebGPU to classify errors
41/// returned by [`wgpu_core`](crate).
42pub trait WebGpuError: error::Error + 'static {
43    /// Determine the classification of this error as a WebGPU [`ErrorType`].
44    fn webgpu_error_type(&self) -> ErrorType;
45}
46
47/// The callback of [`uncaptured_error`](https://gpuweb.github.io/gpuweb/#eventdef-gpudevice-uncapturederror)
48///
49/// It must be a function with this signature.
50pub trait UncapturedErrorHandler: Fn(Error) + Send + Sync + 'static {}
51impl<T> UncapturedErrorHandler for T where T: Fn(Error) + Send + Sync + 'static {}
52
53/// Kinds of [`Error`]s a [`push_error_scope`](https://gpuweb.github.io/gpuweb/#dom-gpudevice-pusherrorscope) may be configured to catch.
54///
55/// Corresponds to the [`GPUErrorFilter`] type in the WebGPU API.
56///
57/// [`GPUErrorFilter`]: https://gpuweb.github.io/gpuweb/#enumdef-gpuerrorfilter
58#[derive(Clone, Copy, Debug, Eq, PartialEq, PartialOrd)]
59pub enum ErrorFilter {
60    /// Catch only out-of-memory errors.
61    OutOfMemory,
62    /// Catch only validation errors.
63    Validation,
64    /// Catch only internal errors.
65    Internal,
66}
67static_assertions::assert_impl_all!(ErrorFilter: Send, Sync);
68
69/// Lower level source of the error.
70///
71/// `Send + Sync` varies depending on configuration.
72#[cfg(any(
73    not(target_family = "wasm"),
74    all(
75        feature = "fragile-send-sync-non-atomic-wasm",
76        not(target_feature = "atomics")
77    )
78))]
79#[cfg_attr(docsrs, doc(cfg(all())))]
80pub type ErrorSource = Box<dyn error::Error + Send + Sync + 'static>;
81/// Lower level source of the error.
82///
83/// `Send + Sync` varies depending on configuration.
84#[cfg(not(any(
85    not(target_family = "wasm"),
86    all(
87        feature = "fragile-send-sync-non-atomic-wasm",
88        not(target_feature = "atomics")
89    )
90)))]
91#[cfg_attr(docsrs, doc(cfg(all())))]
92pub type ErrorSource = Box<dyn error::Error + 'static>;
93
94/// Errors resulting from usage of GPU APIs.
95#[derive(Debug)]
96pub enum Error {
97    /// Out of memory.
98    OutOfMemory {
99        /// Lower level source of the error.
100        source: ErrorSource,
101    },
102    /// Validation error, signifying a bug in code or data provided to `wgpu`.
103    Validation {
104        /// Lower level source of the error.
105        source: ErrorSource,
106        /// Description of the validation error.
107        description: String,
108    },
109    /// Internal error. Used for signalling any failures not explicitly expected by WebGPU.
110    ///
111    /// These could be due to internal implementation or system limits being reached.
112    Internal {
113        /// Lower level source of the error.
114        source: ErrorSource,
115        /// Description of the internal GPU error.
116        description: String,
117    },
118}
119
120impl error::Error for Error {
121    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
122        match self {
123            Error::OutOfMemory { source } => Some(source.as_ref()),
124            Error::Validation { source, .. } => Some(source.as_ref()),
125            Error::Internal { source, .. } => Some(source.as_ref()),
126        }
127    }
128}
129
130impl fmt::Display for Error {
131    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
132        match self {
133            Error::OutOfMemory { .. } => f.write_str("Out of Memory"),
134            Error::Validation { description, .. } => f.write_str(description),
135            Error::Internal { description, .. } => f.write_str(description),
136        }
137    }
138}
139
140impl WebGpuError for Error {
141    fn webgpu_error_type(&self) -> ErrorType {
142        match self {
143            Error::OutOfMemory { .. } => ErrorType::OutOfMemory,
144            Error::Validation { .. } => ErrorType::Validation,
145            Error::Internal { .. } => ErrorType::Internal,
146        }
147    }
148}
wgpu_types/error.rs

wgpu_types/
error.rs
