vortex_error/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4#![deny(missing_docs)]
5
6//! This crate defines error & result types for Vortex.
7//! It also contains a variety of useful macros for error handling.
8
9#[cfg(feature = "python")]
10pub mod python;
11
12use std::backtrace::Backtrace;
13use std::borrow::Cow;
14use std::convert::Infallible;
15use std::error::Error;
16use std::fmt::{Debug, Display, Formatter};
17use std::num::TryFromIntError;
18use std::ops::Deref;
19use std::sync::{Arc, PoisonError};
20use std::{env, fmt, io};
21
22/// A string that can be used as an error message.
23#[derive(Debug)]
24pub struct ErrString(Cow<'static, str>);
25
26#[allow(clippy::fallible_impl_from)]
27impl<T> From<T> for ErrString
28where
29    T: Into<Cow<'static, str>>,
30{
31    #[allow(clippy::panic)]
32    fn from(msg: T) -> Self {
33        if env::var("VORTEX_PANIC_ON_ERR").as_deref().unwrap_or("") == "1" {
34            panic!("{}\nBacktrace:\n{}", msg.into(), Backtrace::capture());
35        } else {
36            Self(msg.into())
37        }
38    }
39}
40
41impl AsRef<str> for ErrString {
42    fn as_ref(&self) -> &str {
43        &self.0
44    }
45}
46
47impl Deref for ErrString {
48    type Target = str;
49
50    fn deref(&self) -> &Self::Target {
51        &self.0
52    }
53}
54
55impl Display for ErrString {
56    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
57        Display::fmt(&self.0, f)
58    }
59}
60
61impl From<Infallible> for VortexError {
62    fn from(_: Infallible) -> Self {
63        unreachable!()
64    }
65}
66
67const _: () = {
68    assert!(size_of::<VortexError>() < 128);
69};
70/// The top-level error type for Vortex.
71#[non_exhaustive]
72pub enum VortexError {
73    /// A wrapped generic error
74    Generic(Box<dyn Error + Send + Sync + 'static>, Box<Backtrace>),
75    /// An index is out of bounds.
76    OutOfBounds(usize, usize, usize, Box<Backtrace>),
77    /// An error occurred while executing a compute kernel.
78    ComputeError(ErrString, Box<Backtrace>),
79    /// An invalid argument was provided.
80    InvalidArgument(ErrString, Box<Backtrace>),
81    /// The system has reached an invalid state,
82    InvalidState(ErrString, Box<Backtrace>),
83    /// An error occurred while serializing or deserializing.
84    InvalidSerde(ErrString, Box<Backtrace>),
85    /// An unimplemented function was called.
86    NotImplemented(ErrString, ErrString, Box<Backtrace>),
87    /// A type mismatch occurred.
88    MismatchedTypes(ErrString, ErrString, Box<Backtrace>),
89    /// An assertion failed.
90    AssertionFailed(ErrString, Box<Backtrace>),
91    /// A wrapper for other errors, carrying additional context.
92    Context(ErrString, Box<VortexError>),
93    /// A wrapper for shared errors that require cloning.
94    Shared(Arc<VortexError>),
95    /// A wrapper for errors from the Arrow library.
96    ArrowError(arrow_schema::ArrowError, Box<Backtrace>),
97    /// A wrapper for errors from the FlatBuffers library.
98    #[cfg(feature = "flatbuffers")]
99    FlatBuffersError(flatbuffers::InvalidFlatbuffer, Box<Backtrace>),
100    /// A wrapper for formatting errors.
101    FmtError(fmt::Error, Box<Backtrace>),
102    /// A wrapper for IO errors.
103    IOError(io::Error, Box<Backtrace>),
104    /// A wrapper for errors from the standard library when converting a slice to an array.
105    TryFromSliceError(std::array::TryFromSliceError, Box<Backtrace>),
106    /// A wrapper for errors from the Object Store library.
107    #[cfg(feature = "object_store")]
108    ObjectStore(object_store::Error, Box<Backtrace>),
109    /// A wrapper for errors from the Jiff library.
110    JiffError(jiff::Error, Box<Backtrace>),
111    /// A wrapper for Tokio join error.
112    #[cfg(feature = "tokio")]
113    JoinError(tokio::task::JoinError, Box<Backtrace>),
114    /// A wrapper for URL parsing errors.
115    UrlError(url::ParseError, Box<Backtrace>),
116    /// Wrap errors for fallible integer casting.
117    TryFromInt(TryFromIntError, Box<Backtrace>),
118    /// Wrap serde and serde json errors
119    #[cfg(feature = "serde")]
120    SerdeJsonError(serde_json::Error, Box<Backtrace>),
121    /// Wrap prost encode error
122    #[cfg(feature = "prost")]
123    ProstEncodeError(prost::EncodeError, Box<Backtrace>),
124    /// Wrap prost decode error
125    #[cfg(feature = "prost")]
126    ProstDecodeError(prost::DecodeError, Box<Backtrace>),
127    /// Wrap prost unknown enum value
128    #[cfg(feature = "prost")]
129    ProstUnknownEnumValue(prost::UnknownEnumValue, Box<Backtrace>),
130}
131
132impl VortexError {
133    /// Adds additional context to an error.
134    pub fn with_context<T: Into<ErrString>>(self, msg: T) -> Self {
135        VortexError::Context(msg.into(), Box::new(self))
136    }
137
138    /// Wrap an a generic error into a Vortex error
139    pub fn generic(err: Box<dyn Error + Send + Sync + 'static>) -> Self {
140        Self::Generic(err, Box::new(Backtrace::capture()))
141    }
142}
143
144impl Display for VortexError {
145    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
146        match self {
147            VortexError::Generic(err, backtrace) => {
148                write!(f, "{err}\nBacktrace:\n{backtrace}")
149            }
150            VortexError::OutOfBounds(idx, start, stop, backtrace) => {
151                write!(
152                    f,
153                    "index {idx} out of bounds from {start} to {stop}\nBacktrace:\n{backtrace}",
154                )
155            }
156            VortexError::ComputeError(msg, backtrace) => {
157                write!(f, "{msg}\nBacktrace:\n{backtrace}")
158            }
159            VortexError::InvalidArgument(msg, backtrace) => {
160                write!(f, "{msg}\nBacktrace:\n{backtrace}")
161            }
162            VortexError::InvalidState(msg, backtrace) => {
163                write!(f, "{msg}\nBacktrace:\n{backtrace}")
164            }
165            VortexError::InvalidSerde(msg, backtrace) => {
166                write!(f, "{msg}\nBacktrace:\n{backtrace}")
167            }
168            VortexError::NotImplemented(func, by_whom, backtrace) => {
169                write!(
170                    f,
171                    "function {func} not implemented for {by_whom}\nBacktrace:\n{backtrace}",
172                )
173            }
174            VortexError::MismatchedTypes(expected, actual, backtrace) => {
175                write!(
176                    f,
177                    "expected type: {expected} but instead got {actual}\nBacktrace:\n{backtrace}",
178                )
179            }
180            VortexError::AssertionFailed(msg, backtrace) => {
181                write!(f, "{msg}\nBacktrace:\n{backtrace}")
182            }
183            VortexError::Context(msg, inner) => {
184                write!(f, "{msg}: {inner}")
185            }
186            VortexError::Shared(inner) => Display::fmt(inner, f),
187            VortexError::ArrowError(err, backtrace) => {
188                write!(f, "{err}\nBacktrace:\n{backtrace}")
189            }
190            #[cfg(feature = "flatbuffers")]
191            VortexError::FlatBuffersError(err, backtrace) => {
192                write!(f, "{err}\nBacktrace:\n{backtrace}")
193            }
194            VortexError::FmtError(err, backtrace) => {
195                write!(f, "{err}\nBacktrace:\n{backtrace}")
196            }
197            VortexError::IOError(err, backtrace) => {
198                write!(f, "{err}\nBacktrace:\n{backtrace}")
199            }
200            VortexError::TryFromSliceError(err, backtrace) => {
201                write!(f, "{err}\nBacktrace:\n{backtrace}")
202            }
203            #[cfg(feature = "object_store")]
204            VortexError::ObjectStore(err, backtrace) => {
205                write!(f, "{err}\nBacktrace:\n{backtrace}")
206            }
207            VortexError::JiffError(err, backtrace) => {
208                write!(f, "{err}\nBacktrace:\n{backtrace}")
209            }
210            #[cfg(feature = "tokio")]
211            VortexError::JoinError(err, backtrace) => {
212                write!(f, "{err}\nBacktrace:\n{backtrace}")
213            }
214            VortexError::UrlError(err, backtrace) => {
215                write!(f, "{err}\nBacktrace:\n{backtrace}")
216            }
217            VortexError::TryFromInt(err, backtrace) => {
218                write!(f, "{err}\nBacktrace:\n{backtrace}")
219            }
220            #[cfg(feature = "serde")]
221            VortexError::SerdeJsonError(err, backtrace) => {
222                write!(f, "{err}\nBacktrace:\n{backtrace}")
223            }
224            #[cfg(feature = "prost")]
225            VortexError::ProstEncodeError(err, backtrace) => {
226                write!(f, "{err}\nBacktrace:\n{backtrace}")
227            }
228            #[cfg(feature = "prost")]
229            VortexError::ProstDecodeError(err, backtrace) => {
230                write!(f, "{err}\nBacktrace:\n{backtrace}")
231            }
232            #[cfg(feature = "prost")]
233            VortexError::ProstUnknownEnumValue(err, backtrace) => {
234                write!(f, "{err}\nBacktrace:\n{backtrace}")
235            }
236        }
237    }
238}
239
240impl Error for VortexError {
241    fn source(&self) -> Option<&(dyn Error + 'static)> {
242        match self {
243            VortexError::Generic(err, _) => Some(err.as_ref()),
244            VortexError::Context(_, inner) => inner.source(),
245            VortexError::Shared(inner) => inner.source(),
246            VortexError::ArrowError(err, _) => Some(err),
247            #[cfg(feature = "flatbuffers")]
248            VortexError::FlatBuffersError(err, _) => Some(err),
249            VortexError::IOError(err, _) => Some(err),
250            #[cfg(feature = "object_store")]
251            VortexError::ObjectStore(err, _) => Some(err),
252            VortexError::JiffError(err, _) => Some(err),
253            #[cfg(feature = "tokio")]
254            VortexError::JoinError(err, _) => Some(err),
255            VortexError::UrlError(err, _) => Some(err),
256            #[cfg(feature = "serde")]
257            VortexError::SerdeJsonError(err, _) => Some(err),
258            #[cfg(feature = "prost")]
259            VortexError::ProstEncodeError(err, _) => Some(err),
260            #[cfg(feature = "prost")]
261            VortexError::ProstDecodeError(err, _) => Some(err),
262            #[cfg(feature = "prost")]
263            VortexError::ProstUnknownEnumValue(err, _) => Some(err),
264            _ => None,
265        }
266    }
267}
268
269impl Debug for VortexError {
270    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
271        Display::fmt(self, f)
272    }
273}
274
275/// A type alias for Results that return VortexErrors as their error type.
276pub type VortexResult<T> = Result<T, VortexError>;
277
278/// A vortex result that can be shared or cloned.
279pub type SharedVortexResult<T> = Result<T, Arc<VortexError>>;
280
281impl From<Arc<VortexError>> for VortexError {
282    fn from(value: Arc<VortexError>) -> Self {
283        Self::from(&value)
284    }
285}
286
287impl From<&Arc<VortexError>> for VortexError {
288    fn from(e: &Arc<VortexError>) -> Self {
289        if let VortexError::Shared(e_inner) = e.as_ref() {
290            // don't re-wrap
291            VortexError::Shared(Arc::clone(e_inner))
292        } else {
293            VortexError::Shared(Arc::clone(e))
294        }
295    }
296}
297
298/// A trait for unwrapping a VortexResult.
299pub trait VortexUnwrap {
300    /// The type of the value being unwrapped.
301    type Output;
302
303    /// Returns the value of the result if it is Ok, otherwise panics with the error.
304    /// Should be called only in contexts where the error condition represents a bug (programmer error).
305    fn vortex_unwrap(self) -> Self::Output;
306}
307
308impl<T, E> VortexUnwrap for Result<T, E>
309where
310    E: Into<VortexError>,
311{
312    type Output = T;
313
314    #[inline(always)]
315    fn vortex_unwrap(self) -> Self::Output {
316        self.map_err(|err| err.into())
317            .unwrap_or_else(|err| vortex_panic!(err))
318    }
319}
320
321/// A trait for expect-ing a VortexResult or an Option.
322pub trait VortexExpect {
323    /// The type of the value being expected.
324    type Output;
325
326    /// Returns the value of the result if it is Ok, otherwise panics with the error.
327    /// Should be called only in contexts where the error condition represents a bug (programmer error).
328    fn vortex_expect(self, msg: &str) -> Self::Output;
329}
330
331impl<T, E> VortexExpect for Result<T, E>
332where
333    E: Into<VortexError>,
334{
335    type Output = T;
336
337    #[inline(always)]
338    fn vortex_expect(self, msg: &str) -> Self::Output {
339        self.map_err(|err| err.into())
340            .unwrap_or_else(|e| vortex_panic!(e.with_context(msg.to_string())))
341    }
342}
343
344impl<T> VortexExpect for Option<T> {
345    type Output = T;
346
347    #[inline(always)]
348    fn vortex_expect(self, msg: &str) -> Self::Output {
349        self.unwrap_or_else(|| {
350            let err = VortexError::AssertionFailed(
351                msg.to_string().into(),
352                Box::new(Backtrace::capture()),
353            );
354            vortex_panic!(err)
355        })
356    }
357}
358
359/// A convenient macro for creating a VortexError.
360#[macro_export]
361macro_rules! vortex_err {
362    (AssertionFailed: $($tts:tt)*) => {{
363        use std::backtrace::Backtrace;
364        let err_string = format!($($tts)*);
365        $crate::__private::must_use(
366            $crate::VortexError::AssertionFailed(err_string.into(), Box::new(Backtrace::capture()))
367        )
368    }};
369    (IOError: $($tts:tt)*) => {{
370        use std::backtrace::Backtrace;
371        $crate::__private::must_use(
372            $crate::VortexError::IOError(err_string.into(), Box::new(Backtrace::capture()))
373        )
374    }};
375    (OutOfBounds: $idx:expr, $start:expr, $stop:expr) => {{
376        use std::backtrace::Backtrace;
377        $crate::__private::must_use(
378            $crate::VortexError::OutOfBounds($idx, $start, $stop, Box::new(Backtrace::capture()))
379        )
380    }};
381    (NotImplemented: $func:expr, $by_whom:expr) => {{
382        use std::backtrace::Backtrace;
383        $crate::__private::must_use(
384            $crate::VortexError::NotImplemented($func.into(), format!("{}", $by_whom).into(), Box::new(Backtrace::capture()))
385        )
386    }};
387    (MismatchedTypes: $expected:literal, $actual:expr) => {{
388        use std::backtrace::Backtrace;
389        $crate::__private::must_use(
390            $crate::VortexError::MismatchedTypes($expected.into(), $actual.to_string().into(), Box::new(Backtrace::capture()))
391        )
392    }};
393    (MismatchedTypes: $expected:expr, $actual:expr) => {{
394        use std::backtrace::Backtrace;
395        $crate::__private::must_use(
396            $crate::VortexError::MismatchedTypes($expected.to_string().into(), $actual.to_string().into(), Box::new(Backtrace::capture()))
397        )
398    }};
399    (Context: $msg:literal, $err:expr) => {{
400        $crate::__private::must_use(
401            $crate::VortexError::Context($msg.into(), Box::new($err))
402        )
403    }};
404    ($variant:ident: $fmt:literal $(, $arg:expr)* $(,)?) => {{
405        use std::backtrace::Backtrace;
406        $crate::__private::must_use(
407            $crate::VortexError::$variant(format!($fmt, $($arg),*).into(), Box::new(Backtrace::capture()))
408        )
409    }};
410    ($variant:ident: $err:expr $(,)?) => {
411        $crate::__private::must_use(
412            $crate::VortexError::$variant($err)
413        )
414    };
415    ($fmt:literal $(, $arg:expr)* $(,)?) => {
416        $crate::vortex_err!(InvalidArgument: $fmt, $($arg),*)
417    };
418}
419
420/// A convenient macro for returning a VortexError.
421#[macro_export]
422macro_rules! vortex_bail {
423    ($($tt:tt)+) => {
424        return Err($crate::vortex_err!($($tt)+))
425    };
426}
427
428/// A macro that mirrors `assert!` but instead of panicking on a failed condition,
429/// it will immediately return an erroneous `VortexResult` to the calling context.
430#[macro_export]
431macro_rules! vortex_ensure {
432    ($cond:expr) => {
433        vortex_ensure!($cond, AssertionFailed: "{}", stringify!($cond));
434    };
435    ($cond:expr, $($tt:tt)*) => {
436        if !$cond {
437            $crate::vortex_bail!($($tt)*);
438        }
439    };
440}
441
442/// A convenient macro for panicking with a VortexError in the presence of a programmer error
443/// (e.g., an invariant has been violated).
444#[macro_export]
445macro_rules! vortex_panic {
446    (OutOfBounds: $idx:expr, $start:expr, $stop:expr) => {{
447        $crate::vortex_panic!($crate::vortex_err!(OutOfBounds: $idx, $start, $stop))
448    }};
449    (NotImplemented: $func:expr, $for_whom:expr) => {{
450        $crate::vortex_panic!($crate::vortex_err!(NotImplemented: $func, $for_whom))
451    }};
452    (MismatchedTypes: $expected:literal, $actual:expr) => {{
453        $crate::vortex_panic!($crate::vortex_err!(MismatchedTypes: $expected, $actual))
454    }};
455    (MismatchedTypes: $expected:expr, $actual:expr) => {{
456        $crate::vortex_panic!($crate::vortex_err!(MismatchedTypes: $expected, $actual))
457    }};
458    (Context: $msg:literal, $err:expr) => {{
459        $crate::vortex_panic!($crate::vortex_err!(Context: $msg, $err))
460    }};
461    ($variant:ident: $fmt:literal $(, $arg:expr)* $(,)?) => {
462        $crate::vortex_panic!($crate::vortex_err!($variant: $fmt, $($arg),*))
463    };
464    ($err:expr, $fmt:literal $(, $arg:expr)* $(,)?) => {{
465        let err: $crate::VortexError = $err;
466        panic!("{}", err.with_context(format!($fmt, $($arg),*)))
467    }};
468    ($fmt:literal $(, $arg:expr)* $(,)?) => {
469        $crate::vortex_panic!($crate::vortex_err!($fmt, $($arg),*))
470    };
471    ($err:expr) => {{
472        let err: $crate::VortexError = $err;
473        panic!("{}", err)
474    }};
475}
476
477impl From<arrow_schema::ArrowError> for VortexError {
478    fn from(value: arrow_schema::ArrowError) -> Self {
479        VortexError::ArrowError(value, Box::new(Backtrace::capture()))
480    }
481}
482
483#[cfg(feature = "flatbuffers")]
484impl From<flatbuffers::InvalidFlatbuffer> for VortexError {
485    fn from(value: flatbuffers::InvalidFlatbuffer) -> Self {
486        VortexError::FlatBuffersError(value, Box::new(Backtrace::capture()))
487    }
488}
489
490impl From<io::Error> for VortexError {
491    fn from(value: io::Error) -> Self {
492        VortexError::IOError(value, Box::new(Backtrace::capture()))
493    }
494}
495
496impl From<std::array::TryFromSliceError> for VortexError {
497    fn from(value: std::array::TryFromSliceError) -> Self {
498        VortexError::TryFromSliceError(value, Box::new(Backtrace::capture()))
499    }
500}
501
502#[cfg(feature = "object_store")]
503impl From<object_store::Error> for VortexError {
504    fn from(value: object_store::Error) -> Self {
505        VortexError::ObjectStore(value, Box::new(Backtrace::capture()))
506    }
507}
508
509impl From<jiff::Error> for VortexError {
510    fn from(value: jiff::Error) -> Self {
511        VortexError::JiffError(value, Box::new(Backtrace::capture()))
512    }
513}
514
515#[cfg(feature = "tokio")]
516impl From<tokio::task::JoinError> for VortexError {
517    fn from(value: tokio::task::JoinError) -> Self {
518        VortexError::JoinError(value, Box::new(Backtrace::capture()))
519    }
520}
521
522impl From<url::ParseError> for VortexError {
523    fn from(value: url::ParseError) -> Self {
524        VortexError::UrlError(value, Box::new(Backtrace::capture()))
525    }
526}
527
528impl From<TryFromIntError> for VortexError {
529    fn from(value: TryFromIntError) -> Self {
530        VortexError::TryFromInt(value, Box::new(Backtrace::capture()))
531    }
532}
533
534#[cfg(feature = "serde")]
535impl From<serde_json::Error> for VortexError {
536    fn from(value: serde_json::Error) -> Self {
537        VortexError::SerdeJsonError(value, Box::new(Backtrace::capture()))
538    }
539}
540
541#[cfg(feature = "prost")]
542impl From<prost::EncodeError> for VortexError {
543    fn from(value: prost::EncodeError) -> Self {
544        VortexError::ProstEncodeError(value, Box::new(Backtrace::capture()))
545    }
546}
547
548#[cfg(feature = "prost")]
549impl From<prost::DecodeError> for VortexError {
550    fn from(value: prost::DecodeError) -> Self {
551        VortexError::ProstDecodeError(value, Box::new(Backtrace::capture()))
552    }
553}
554
555#[cfg(feature = "prost")]
556impl From<prost::UnknownEnumValue> for VortexError {
557    fn from(value: prost::UnknownEnumValue) -> Self {
558        VortexError::ProstUnknownEnumValue(value, Box::new(Backtrace::capture()))
559    }
560}
561
562// Not public, referenced by macros only.
563#[doc(hidden)]
564pub mod __private {
565    #[doc(hidden)]
566    #[inline]
567    #[cold]
568    #[must_use]
569    pub const fn must_use(error: crate::VortexError) -> crate::VortexError {
570        error
571    }
572}
573
574impl<T> From<PoisonError<T>> for VortexError {
575    fn from(_value: PoisonError<T>) -> Self {
576        // We don't include the value since it may be sensitive.
577        Self::InvalidState("Lock poisoned".into(), Box::new(Backtrace::capture()))
578    }
579}
vortex_error/lib.rs

vortex_error/
lib.rs
