macros.rs

//! Macro definitions and the private runtime functions used in their generated
//! code.

// Items used by macro-generated code.
pub use core::format_args;
pub use core::result::Result::Err;

use super::{Error, OutOfMemory};
use core::fmt::{self, write};
use std_alloc::string::String;

/// Construct an [`Error`] via string formatting or another error.
///
/// Like `anyhow::format_err!` or `anyhow::anyhow!` but for
/// [`wasmtime::Error`](Error).
///
/// # String Formatting
///
/// When a string literal is the first argument, it is interpreted as a format
/// string template and the rest of the arguments are format arguments:
///
/// ```
/// # use wasmtime_internal_core::error as wasmtime;
/// use wasmtime::{format_err, Error};
///
/// let x = 42;
/// let error: Error = format_err!("x is {x}");
/// assert_eq!(error.to_string(), "x is 42");
///
/// let error: Error = format_err!("x / 2 is {}", x / 2);
/// assert_eq!(error.to_string(), "x / 2 is 21");
///
/// let error: Error = format_err!("x + 1 is {y}", y = x + 1);
/// assert_eq!(error.to_string(), "x + 1 is 43");
/// ```
///
/// # From Another Error
///
/// When a string literal is not the first argument, then it is treated as a
/// foreign error and is converted into an [`Error`]. The argument
/// must be of a type that can be passed to either [`Error::new`] or
/// [`Error::msg`].
///
/// ```
/// # fn _foo() {
/// #![cfg(feature = "std")]
/// # use wasmtime_internal_core::error as wasmtime;
/// use std::fmt;
/// use wasmtime::{format_err, Error};
///
/// #[derive(Debug)]
/// struct SomeOtherError(u32);
///
/// impl fmt::Display for SomeOtherError {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         write!(f, "some other error (code {})", self.0)
///     }
/// }
///
/// impl std::error::Error for SomeOtherError {}
///
/// let error: Error = format_err!(SomeOtherError(36));
/// assert!(error.is::<SomeOtherError>());
/// assert_eq!(error.to_string(), "some other error (code 36)");
/// # }
/// ```
///
/// # From an `anyhow::Error`
///
/// The `format_err!` macro can always convert an `anyhow::Error` into a
/// `wasmtime::Error`, but when the `"anyhow"` cargo feature is enabled the
/// resulting error will also return true for
/// [`error.is::<anyhow::Error>()`](Error::is) invocations.
///
/// ```
/// # fn _foo() {
/// #![cfg(feature = "anyhow")]
/// # use wasmtime_internal_core::error as wasmtime;
/// use wasmtime::format_err;
///
/// let anyhow_error: anyhow::Error = anyhow::anyhow!("aw crap");
/// let wasmtime_error: wasmtime::Error = format_err!(anyhow_error);
/// assert!(wasmtime_error.is::<anyhow::Error>());
/// # }
/// ```
#[macro_export]
macro_rules! format_err {
    // Format-style invocation without explicit format arguments.
    ( $message:literal $(,)? ) => {
        $crate::error::Error::from_format_args($crate::error::macros::format_args!($message))
    };

    // Format-style invocation with explicit format arguments.
    ( $message:literal , $( $args:tt )* ) => {
        $crate::error::Error::from_format_args($crate::error::macros::format_args!($message , $( $args )* ))
    };

    // Do either `Error::new($error)` or `Error::msg($error)` depending on
    // whether `$error` implements `core::error::Error` or not.
    ( $error:expr $(,)? ) => {{
        use $crate::error::macros::ctor_specialization::*;
        let error = $error;
        (&&&error).wasmtime_error_choose_ctor().construct(error)
    }};
}

/// Identical to the [`format_err!`] macro.
///
/// This is provided for API compatibility with the `anyhow` crate, but you
/// should prefer using `format_err!` instead.
#[macro_export]
#[deprecated = "Use `format_err!(...)` instead"]
macro_rules! anyhow {
    ( $( $args:tt )* ) => {
        $crate::error::format_err!( $( $args )* )
    };
}

/// Early exit from the current function with an error.
///
/// This helper is equivalent to `return Err(format_err!(...))`.
///
/// See the docs for the [`format_err!`] macro for details on
/// the kinds of errors that can be constructed.
///
/// Like `anyhow::bail!` but for [`wasmtime::Error`](Error).
///
/// # Example
///
/// ```
/// # use wasmtime_internal_core::error as wasmtime;
/// use wasmtime::{bail, Result};
///
/// fn error_on_none(option: Option<u32>) -> Result<u32> {
///     match option {
///         None => bail!("`error_on_none` got `None`!"),
///         Some(x) => Ok(x),
///     }
/// }
///
/// let x = error_on_none(Some(42)).unwrap();
/// assert_eq!(x, 42);
///
/// let error = error_on_none(None).unwrap_err();
/// assert_eq!(
///     error.to_string(),
///     "`error_on_none` got `None`!",
/// );
/// ```
#[macro_export]
macro_rules! bail {
    ( $($args:tt)* ) => {{
        return $crate::error::macros::Err($crate::error::format_err!( $( $args )* ));
    }};
}

/// Ensure that a condition holds true, or else early exit from the current
/// function with an error.
///
/// `ensure!(condition, ...)` is equivalent to the following:
///
/// ```ignore
/// if !condition {
///     return Err(format_err!(...));
/// }
/// ```
///
/// Like `anyhow::ensure!` but for [`wasmtime::Error`](Error).
///
/// # Example
///
/// ```rust
/// # use wasmtime_internal_core::error as wasmtime;
/// use wasmtime::{ensure, Result};
///
/// fn checked_div(a: u32, b: u32) -> Result<u32> {
///     ensure!(b != 0, "cannot divide by zero: {a} / {b}");
///     Ok(a / b)
/// }
///
/// let x = checked_div(6, 2).unwrap();
/// assert_eq!(x, 3);
///
/// let error = checked_div(9, 0).unwrap_err();
/// assert_eq!(
///     error.to_string(),
///     "cannot divide by zero: 9 / 0",
/// );
/// ```
#[macro_export]
macro_rules! ensure {
    ( $condition:expr ) => {{
        $crate::error::ensure!($condition, concat!("Condition failed: `", stringify!($condition), "`"))
    }};

    ( $condition:expr , $( $args:tt )* ) => {{
        if $crate::error::macros::ensure::not($condition) {
            $crate::error::bail!( $( $args )* );
        }
    }};
}

/// We don't have specialization in stable Rust, so do a poor-person's
/// equivalent by hacking Rust's method name resolution and auto-deref. Given
/// that we have `n` versions of the "same" method, we do the following:
///
/// * We define `n` different traits, which each define the same trait method
///   name. The method need not have the same type across traits, but each must
///   type-check when chosen by method resolution at a particular call site.
///
/// * We implement each trait for an `i`-deep borrow of the type(s) we want to
///   specialize the `i`th implementation on, for example:
///
///   ```ignore
///   impl Specialization1 for &MyType { ... }
///   impl Specialization2 for &&OtherType { ... }
///   impl Specialization3 for &&&AnotherType { ... }
///   ```
///
/// * Call sites must have all specialization traits in scope and must borrow
///   the receiver `n` times before calling the method. Rust's method name
///   resolution will choose the method with the least number of references that
///   is well-typed. Therefore, specialization implementations for lower numbers
///   of borrows are preferred over those with higher numbers of borrows when
///   specializations overlap. For example, if both `<&&&T as
///   Specialization3>::method` and `<&T as Specialization1>::method` are
///   well-typed at the trait method call site `(&&&&&t).method()`, then
///   `Specialization1` will be prioritized over `Specialization3`.
///
/// In our specific case here of choosing an `Error` constructor, we have
/// three specializations:
///
/// 1. For `anyhow::Error`, we want to use the `Error::from_anyhow` constructor.
///
/// 2. When the type implements `core::error::Error`, we want to use the
///    `Error::new` constructor, which will preserve
///    `core::error::Error::source` chains.
///
/// 3. Otherwise, we want to use the `Error::msg` constructor.
///
/// The `*CtorTrait`s are our `n` specialization traits. Their
/// `wasmtime_error_choose_ctor` methods will return different types, each of
/// which is a dispatcher to their associated constructor. Those dispatchers
/// each have a constructor signature that is syntactically identical, but only
/// guaranteed to be well-typed based on the specialization that we did by
/// getting the dispatcher in the first place.
pub mod ctor_specialization {
    use super::*;

    #[cfg(feature = "anyhow")]
    pub use anyhow::*;
    #[cfg(feature = "anyhow")]
    mod anyhow {
        use super::*;

        pub trait AnyhowCtorTrait {
            #[inline]
            fn wasmtime_error_choose_ctor(&self) -> AnyhowCtor {
                AnyhowCtor
            }
        }

        impl AnyhowCtorTrait for &anyhow::Error {}

        pub struct AnyhowCtor;

        impl AnyhowCtor {
            #[inline]
            pub fn construct(&self, anyhow_error: ::anyhow::Error) -> Error {
                Error::from_anyhow(anyhow_error)
            }
        }
    }

    pub trait NewCtorTrait {
        #[inline]
        fn wasmtime_error_choose_ctor(&self) -> NewCtor {
            NewCtor
        }
    }

    impl<E: core::error::Error + Send + Sync + 'static> NewCtorTrait for &&E {}

    pub struct NewCtor;

    impl NewCtor {
        #[inline]
        pub fn construct<E>(&self, error: E) -> Error
        where
            E: core::error::Error + Send + Sync + 'static,
        {
            Error::new(error)
        }
    }

    pub trait MsgCtorTrait {
        #[inline]
        fn wasmtime_error_choose_ctor(&self) -> MsgCtor {
            MsgCtor
        }
    }

    impl<M: fmt::Debug + fmt::Display + Send + Sync + 'static> MsgCtorTrait for &&&M {}

    pub struct MsgCtor;

    impl MsgCtor {
        #[inline]
        pub fn construct<M>(&self, message: M) -> Error
        where
            M: fmt::Debug + fmt::Display + Send + Sync + 'static,
        {
            Error::msg(message)
        }
    }
}

/// Runtime code for creating an `Error` from format arguments, handling OOM in
/// the process.
pub mod formatting {
    use super::*;

    #[derive(Default)]
    struct Formatter {
        message: String,
        oom: Option<OutOfMemory>,
    }

    impl fmt::Write for Formatter {
        fn write_str(&mut self, s: &str) -> fmt::Result {
            match self.message.try_reserve(s.len()) {
                Ok(()) => {
                    self.message.push_str(s);
                    Ok(())
                }
                Err(_) => {
                    self.oom = Some(OutOfMemory::new(self.message.len() + s.len()));
                    Err(fmt::Error)
                }
            }
        }
    }

    impl Error {
        /// Construct an `Error` from format arguments.
        ///
        /// Only for use by the `format_err!` macro.
        #[doc(hidden)]
        pub fn from_format_args(args: fmt::Arguments<'_>) -> Self {
            if let Some(s) = args.as_str() {
                return Self::msg(s);
            }

            let mut f = Formatter::default();
            match write(&mut f, args) {
                Ok(()) => {
                    debug_assert!(f.oom.is_none());
                    Error::msg(f.message)
                }
                Err(fmt_error) => match f.oom {
                    Some(oom) => Error::new(oom),
                    None => Error::new(fmt_error),
                },
            }
        }
    }
}

pub mod ensure {
    /// Convenience trait to enable `ensure!(cond, ...)` to work when `cond` is of
    /// type `&bool`, not just `bool`. Saves useless rewrite-to-`*cond` busywork and
    /// matches `anyhow`'s behavior.
    pub trait ToBool {
        fn to_bool(self) -> bool;
    }

    impl ToBool for bool {
        #[inline]
        fn to_bool(self) -> bool {
            self
        }
    }

    impl ToBool for &bool {
        #[inline]
        fn to_bool(self) -> bool {
            *self
        }
    }

    #[inline]
    pub fn not(b: impl ToBool) -> bool {
        !b.to_bool()
    }
}