closure_ffi/

bare_closure.rs

//! Provides the [`BareFnOnce`], [`BareFnMut`] and [`BareFn`] wrapper types which allow closures to
//! be called through context-free unsafe bare functions.
//!
//! Variants which erase the signature of the bare function (e.g. [`UntypedBareFn`]) are also
//! provided. This can be useful when a type needs to own wrappers for functions of different
//! signatures.
//!
//! # Thread Safety
//!
//! The closure wrapper types provided by this module are (trivially) [`Send`] if and only if both
//! the closure's type-erased storage and the executable memory allocator used are.
//!
//! Canonically, they should also always be [`Sync`], as the invariants required for soundly
//! calling the wrapped closure across threads are encoded in the `unsafe`ness of the
//! bare function pointer returned by [`BareFnOnce::leak`], [`BareFnMut::bare`] and
//! [`BareFn::bare`], and documented on these (safe) functions.
//!
//! However, such a [`Sync`] impl makes it very easy to call the bare function in situations where
//! it is not allowed:
//!
//! ```compile_fail
//! use closure_ffi::BareFn;
//! use std::{cell::Cell, thread};
//! let cell = Cell::new(0);
//! // WARNING: `wrapped` is Sync, but not the closure!
//! let wrapped = BareFn::new_c(move || -> u32 {
//!     let val = cell.get();
//!     cell.set(val + 1);
//!     val
//! });
//! // `wrapped` can be borrowed here at is it Sync. But by `bare()` documentation,
//! // calling the function is unsound as the closure is not Sync!
//! thread::scope(|s| {
//!     s.spawn(|| unsafe { wrapped.bare()() });
//!     s.spawn(|| unsafe { wrapped.bare()() });
//! });
//! ```
//!
//! To help guard against this, [`Sync`] is only implemented:
//! - for [`BareFnOnceAny`]: When the closure is [`Send`]. The user is still responsible for
//!   guarding against repeated calls.
//! - for [`BareFnMutAny`]: When the closure is [`Send`]. The user is still responsible for guarding
//!   against unsynchronized calls.
//! - for [`BareFnAny`]: When the closure is [`Sync`].

use alloc::boxed::Box;
use core::{marker::PhantomData, mem::ManuallyDrop};

#[cfg(feature = "proc_macros")]
#[doc(hidden)]
pub use closure_ffi_proc_macros::bare_hrtb as bare_hrtb_impl;

#[cfg(feature = "global_jit_alloc")]
use crate::jit_alloc::GlobalJitAlloc;
#[allow(unused_imports)]
use crate::{
    arch::AllocatedThunk,
    cc,
    jit_alloc::{JitAlloc, JitAllocError},
    traits::{Any, FnMutThunk, FnOnceThunk, FnPtr, FnThunk, ToBoxedDyn},
};

#[cfg(not(feature = "coverage"))]
#[doc(hidden)]
#[macro_export]
macro_rules! bare_hrtb_inner {
    ($($tokens:tt)*) => {
        $crate::bare_closure::bare_hrtb_impl! { $crate, $($tokens)* }
    };
}

#[cfg(feature = "coverage")]
#[doc(hidden)]
#[macro_export]
macro_rules! bare_hrtb_inner {
    ($($tokens:tt)*) => {
        $crate::bare_closure::bare_hrtb_impl! { #[coverage(off)] $crate, $($tokens)* }
    };
}

/// Declares a wrapper type around a higher-ranked bare function which can be used with [BareFn] and
/// friends.
///
/// <div class="warning">
///
/// Note that if using the `coverage` crate feature, the code generated by this macro will require
/// the [`coverage_attribute`](https://doc.rust-lang.org/beta/unstable-book/language-features/coverage-attribute.html)
/// unstable Rust feature to be enabled.
///
/// </div>
///
/// # Usage
///
/// The syntax is equivalent to that of a type alias:
/// ```
/// #![cfg_attr(feature = "coverage", feature(coverage_attribute))]
///
/// closure_ffi::bare_hrtb! {
///     type MyFn = for<'a> extern "C" fn(&'a str) -> &'a u32;
/// }
/// ```
///
/// `unsafe` is automatically added to the function signature if absent. Generic type parameters and
/// bounds can be added to the alias:
/// ```
/// #![cfg_attr(feature = "coverage", feature(coverage_attribute))]
///
/// closure_ffi::bare_hrtb! {
///     type MyFn<T: Clone + 'static> = for<'a> extern "C" fn(&'a T) -> T;
/// }
/// ```
///
/// A calling convention marker type is also created under the alias named suffixed by `_CC`, with
/// the same visibility.
///
/// # Limitations
///
/// ## Maximum of 3 independent lifetimes
///
/// Higher-ranked bare functions with more than 3 independent bound lifetimes are not supported.
/// For example, the following will not compile:
///
/// ```compile_fail
/// #![cfg_attr(feature = "coverage", feature(coverage_attribute))]
///
/// closure_ffi::bare_hrtb! {
///     type MyFn = extern "C" fn<'a, 'b, 'c, 'd>(&'a u8, &'b u8) -> (&'c u8, &'d u8);
/// }
/// ```
///
/// ## No implicit higher-ranked lifetimes
///
/// Furthermore, implicit higher-ranked lifetimes are not supported in the signature. So
/// ```compile_fail
/// #![cfg_attr(feature = "coverage", feature(coverage_attribute))]
///
/// closure_ffi::bare_hrtb! {
///     type MyFn = extern "C" fn(&u8) -> &u8;
/// }
/// ```
///
/// must instead be written as
/// ```
/// #![cfg_attr(feature = "coverage", feature(coverage_attribute))]
///
/// closure_ffi::bare_hrtb! {
///     type MyFn = for<'a> extern "C" fn(&'a u8) -> &'a u8;
/// }
/// ```
///
/// ## Static bound requirements on generic parameters
///
/// Generic parameters whose lifetime is implicitly lower-bounded by one of the `for<...>` lifetimes
/// must be `'static`. For example, the following will not compile without a `'static` bound on `T`
/// and `U`, but no bound is required on `V`:
///
/// ```compile_fail
/// #![cfg_attr(feature = "coverage", feature(coverage_attribute))]
///
/// struct RefMut<'a, T>(&'a mut T);
///
/// closure_ffi::bare_hrtb! {
///     type MyFn<T, U, V> = for<'a> extern "C" fn(&'a T, RefMut<'a, U>) -> V;
/// }
/// ```
///
/// # Why use this macro?
///
/// Higher-ranked bare functions are not automatically supported by `closure-ffi` as
/// - It is not possible to blanket implement traits for them;
/// - Even if it was possible, type inference via closure annotations would become impossible when
///   references are involved.
///
/// Hence the following won't compile:
/// ```compile_fail
/// #![cfg_attr(feature = "coverage", feature(coverage_attribute))]
///
/// use closure_ffi::BareFn;
///
/// fn take_higher_rank_fn(
///     bare_fn: unsafe extern "C" fn(&Option<u32>) -> Option<&u32>
/// ) {}
///
/// let bare_closure = BareFn::new_c(|opt: &Option<u32>| opt.as_ref());
/// take_higher_rank_fn(bare_closure.bare());
/// ```
///
/// However, using the type generated by this macro as the bare function type, we can get it to
/// work:
/// ```
/// #![cfg_attr(feature = "coverage", feature(coverage_attribute))]
///
/// use closure_ffi::{BareFn, bare_hrtb};
///
/// bare_hrtb! {
///     type MyFn = for<'a> extern "C" fn(&'a Option<u32>) -> Option<&'a u32>;
/// }
///
/// fn take_higher_rank_fn(
///     bare_fn: unsafe extern "C" fn(&Option<u32>) -> Option<&u32>
/// ) {}
///
/// // alternatively, BareFn::with_cc(MyFn_CC, |opt| opt.as_ref())
/// let bare_closure = BareFn::<MyFn>::new(|opt| opt.as_ref());
/// take_higher_rank_fn(bare_closure.bare().into());
/// ```
#[cfg(feature = "proc_macros")]
#[macro_export]
macro_rules! bare_hrtb {
    ($($tokens:tt)*) => {
        $crate::bare_hrtb_inner! { $($tokens)* }
    };
}

#[cfg(feature = "proc_macros")]
pub use bare_hrtb;

#[allow(unused_macros)]
macro_rules! cc_shorthand {
    ($fn_name:ident, $trait_ident:ident, $cc_ty:ty, $cc_name:literal $(,$cfg:meta)?) => {
        $(#[cfg(any($cfg, doc))])?
        #[doc = "Create a bare function thunk using the "]
        #[doc = $cc_name]
        #[doc = "calling convention for `fun`."]
        ///
        /// The W^X memory required is allocated using the global JIT allocator.
        #[inline]
        pub fn $fn_name<F>(fun: F) -> Self
        where
            F: ToBoxedDyn<S>,
            ($cc_ty, F): $trait_ident<B>,
        {
            Self::with_cc(<$cc_ty>::default(), fun)
        }
    };
}

macro_rules! cc_shorthand_in {
    ($fn_name:ident, $trait_ident:ident, $cc_ty:ty, $cc_name:literal $(,$cfg:meta)?) => {
        $(#[cfg(any($cfg, doc))])?
        #[doc = "Create a bare function thunk using the "]
        #[doc = $cc_name]
        #[doc = "calling convention for `fun`."]
        ///
        /// The W^X memory required is allocated using the provided JIT allocator.
        #[inline]
        pub fn $fn_name<F>(fun: F, jit_alloc: A) -> Self
        where
            F: ToBoxedDyn<S>,
            ($cc_ty, F): $trait_ident<B>,
        {
            Self::with_cc_in(<$cc_ty>::default(), fun, jit_alloc)
        }
    };
}

macro_rules! bare_closure_impl {
    (
        ty_name: $ty_name:ident,
        erased_ty_name: $erased_ty_name:ident,
        non_sync_alias: $non_sync_alias:ident,
        sync_alias: $sync_alias:ident,
        sync_bounds: ($($sync_bounds: path),*),
        sync_alias_bound: $sync_alias_bound: ty,
        trait_ident: $trait_ident:ident,
        thunk_template: $thunk_template:ident,
        bare_toggle: $bare_toggle:meta,
        bare_receiver: $bare_receiver:ty,
        fn_trait_doc: $fn_trait_doc:literal,
        ty_name_doc: $ty_name_doc:literal,
        with_cc_doc: $with_cc_doc:literal,
        with_cc_in_doc: $with_cc_in_doc:literal,
        try_with_cc_in_doc: $try_with_cc_in_doc:literal,
        non_sync_alias_doc: $non_sync_alias_doc:literal,
        sync_alias_doc: $sync_alias_doc:literal,
        sync_alias_bound_doc: $sync_alias_bound_doc:literal,
        safety_doc: $safety_doc:literal
    ) => {
        #[cfg(feature = "global_jit_alloc")]
        #[cfg_attr(docsrs, doc(cfg(all())))]
        /// Type-erased wrapper around a
        #[doc = $fn_trait_doc]
        /// closure which exposes a pointer to a bare function thunk.
        ///
        /// This type cannot be directly constructed; it must be produced from a
        #[doc = $ty_name_doc]
        /// through the `into_untyped` method or the [`Into`] trait.
        ///
        /// # Type parameters
        /// - `S`: The dynamically-sized type to use to type-erase the closure. Use this to enforce
        ///   lifetime bounds and marker traits which the closure must satisfy, e.g. `S = dyn Send +
        ///   'a`. Without the `unstable` feature, this is limited to [`dyn Any`](Any) and
        ///   combinations of [`Send`] and [`Sync`] marker types.
        /// - `A`: The [`JitAlloc`] implementation used to allocate and free executable memory.
        ///
        /// # Layout
        #[doc = $ty_name_doc]
        /// is `#[repr(transparent)]` with this type, so it is safe to transmute back and forth
        /// provided the type parameters match.
        #[allow(dead_code)]
        pub struct $erased_ty_name<S: ?Sized, A: JitAlloc = GlobalJitAlloc> {
            thunk: AllocatedThunk<A>,
            // We can't directly own the closure, even through an UnsafeCell.
            // Otherwise, holding a reference to a BareFnMut while the bare function is
            // being called would be UB! So we reclaim the pointer in the Drop impl.
            storage: *mut S,
        }

        // We copy the documentation to this type, since IDEs will often fetch it from here for
        // pop-up documentation if neither feature is on
        #[cfg(not(feature = "global_jit_alloc"))]
        /// Type-erased wrapper around a
        #[doc = $fn_trait_doc]
        /// closure which exposes a pointer to a bare function thunk.
        ///
        /// This type cannot be directly constructed; it must be produced from a
        #[doc = $ty_name_doc]
        /// through the `into_untyped` method or the [`Into`] trait.
        ///
        /// # Type parameters
        /// - `S`: The dynamically-sized type to use to type-erase the closure. Use this to enforce
        ///   lifetime bounds and marker traits which the closure must satisfy, e.g. `S = dyn Send +
        ///   'a`. Without the `unstable` feature, this is limited to [`dyn Any`](Any) and
        ///   combinations of [`Send`] and [`Sync`] marker types.
        /// - `A`: The [`JitAlloc`] implementation used to allocate and free executable memory.
        ///
        /// # Layout
        #[doc = $ty_name_doc]
        /// is `#[repr(transparent)]` with this type, so it is safe to transmute back and forth
        /// provided the type parameters match.
        #[allow(dead_code)]
        pub struct $erased_ty_name<S: ?Sized, A: JitAlloc> {
            thunk: AllocatedThunk<A>,
            storage: *mut S,
        }

        // SAFETY: S and A can be moved to other threads
        unsafe impl<S: ?Sized + Send, A: JitAlloc + Send> Send for $erased_ty_name<S, A> {}
        // SAFETY: See macro invocation
        unsafe impl<S: $($sync_bounds+)* ?Sized, A: JitAlloc> Sync for $erased_ty_name<S, A> {}

        impl<S: ?Sized, A: JitAlloc> $erased_ty_name<S, A> {
            #[$bare_toggle]
            /// Return a type-erased pointer to the bare function thunk wrapping the closure.
            ///
            /// # Safety
            /// While this method is safe, using the returned pointer is very much not. In
            /// particular, the only safe thing to do with it is casting it to the exact bare
            /// function signature it had before erasure. Even then, it must not be called when:
            /// - The lifetime of `self` has expired, or `self` has been dropped.
            #[doc = $safety_doc]
            #[inline]
            pub fn bare(self: $bare_receiver) -> *const () {
                self.thunk.thunk_ptr()
            }

            /// Leak the underlying closure, returning the unsafe bare function pointer that invokes
            /// it.
            ///
            /// `self` must be `'static` for this method to be called.
            ///
            /// # Safety
            /// While this method is safe, using the returned pointer is very much not. In
            /// particular, the only safe thing to do with it is casting it to the exact bare
            /// function signature it had before erasure. Even then, it must not be called when:
            #[doc = $safety_doc]
            #[inline]
            pub fn leak(self) -> *const ()
            where
                Self: 'static,
            {
                ManuallyDrop::new(self).thunk.thunk_ptr()
            }

            /// Weaken the bounds of the type-erased storage.
            ///
            /// For example, a [`UntypedBareFn<dyn Send + Sync>`] may be upcast into a [`UntypedBareFn<dyn Send>`].
            pub fn upcast<U: ?Sized>(self) -> $erased_ty_name<U, A>
                where PhantomData<S>: ToBoxedDyn<U>
            {
                // SAFETY: This is fine on stable since all trait objects implementing `ToBoxedDyn`
                // only have the destructor in their vtable.
                //
                // With the `unstable` feature, it's sketchy as a boxed `dyn Subtrait` can `Unsize` into
                // a `dyn Supertrait` when `Subtrait: Supertrait`. However, the undocumented layout of
                // trait object vtables makes the destructor the first entry, so it's fine for now
                // (and the foreseeable future).
                unsafe { core::mem::transmute_copy(&ManuallyDrop::new(self)) }
            }
        }

        impl<B: FnPtr, S: ?Sized, U: ?Sized, A: JitAlloc> From<$ty_name<B, S, A>> for $erased_ty_name<U, A>
            where PhantomData<S>: ToBoxedDyn<U>
        {
            fn from(value: $ty_name<B, S, A>) -> Self {
                value.into_untyped().upcast()
            }
        }

        impl<S: ?Sized, A: JitAlloc> Drop for $erased_ty_name<S, A> {
            fn drop(&mut self) {
                // Free the closure
                // SAFETY:
                // - The caller of `bare()` promised not to call through the thunk after
                // the lifetime of self expires, so no borrow on closure exists
                drop(unsafe { Box::from_raw(self.storage) })
            }
        }

        #[cfg(feature = "global_jit_alloc")]
        #[cfg_attr(docsrs, doc(cfg(all())))]
        /// Wrapper around a
        #[doc = $fn_trait_doc]
        /// closure which exposes a bare function thunk that can invoke it without
        /// additional arguments.
        ///
        /// # Note
        /// This is a generic implementation which allows customizing the closure's
        /// type erased storage, which allows enforcing trait bounds like `Send` and `Sync` when
        /// needed. However, this plays poorly with type inference. Consider using the
        #[doc = $non_sync_alias_doc]
        /// and
        #[doc = $sync_alias_doc]
        /// type aliases for the common cases of [`S = dyn Any + 'a`](Any) (no thread safety constraints)
        /// and
        #[doc = $sync_alias_bound_doc]
        /// (minimum required to safely store/call the closure from other threads), respectively.
        ///
        /// # Type parameters
        /// - `B`: The bare function pointer to expose the closure as. For higher-kinded bare
        ///   function pointers, you will need to use the [`bare_hrtb`] macro to define a wrapper
        ///   type.
        /// - `S`: The dynamically-sized type to use to type-erase the closure. Use this to enforce
        ///   lifetime bounds and marker traits which the closure must satisfy, e.g. `S = dyn Send +
        ///   'a`. Without the `unstable` feature, this is limited to [`dyn Any`](Any) and
        ///   combinations of [`Send`] and [`Sync`] marker types.
        /// - `A`: The [`JitAlloc`] implementation used to allocate and free executable memory.
        #[allow(dead_code)]
        #[repr(transparent)]
        pub struct $ty_name<B: FnPtr, S: ?Sized, A: JitAlloc = GlobalJitAlloc> {
            untyped: $erased_ty_name<S, A>,
            phantom: PhantomData<B>,
        }

        // We copy the documentation to this type, since IDEs will often fetch it from here for
        // pop-up documentation of neither feature is on
        #[cfg(not(feature = "global_jit_alloc"))]
        /// Wrapper around a
        #[doc = $fn_trait_doc]
        /// closure which exposes a bare function thunk that can invoke it without
        /// additional arguments.
        ///
        /// This is a generic implementation which allows customizing the closure's
        /// type erased storage, which allows enforcing trait bounds like `Send` and `Sync` when
        /// needed. However, this plays poorly with type inference. Consider using the
        #[doc = $non_sync_alias_doc]
        /// and
        #[doc = $sync_alias_doc]
        /// type aliases for the common cases of [`S = dyn Any + 'a`](Any) (no thread safety constraints)
        /// and
        #[doc = $sync_alias_bound_doc]
        /// (minimum required to safely store/call the closure from other threads), respectively.
        ///
        /// # Type parameters
        /// - `B`: The bare function pointer to expose the closure as. For higher-kinded bare
        ///   function pointers, you will need to use the [`bare_hrtb`] macro to define a wrapper
        ///   type.
        /// - `S`: The dynamically-sized type to use to type-erase the closure. Use this to enforce
        ///   lifetime bounds and marker traits which the closure must satisfy, e.g. `S = dyn Send +
        ///   'a`. Without the `unstable` feature, this is limited to [`dyn Any`](Any) and
        ///   combinations of [`Send`] and [`Sync`] marker types.
        /// - `A`: The [`JitAlloc`] implementation used to allocate and free executable memory.
        #[allow(dead_code)]
        pub struct $ty_name<B: FnPtr, S: ?Sized, A: JitAlloc> {
            untyped: $erased_ty_name<S, A>,
            phantom: PhantomData<B>,
        }

        // Split the impl blocks so that the relevant functions appear first in docs
        #[cfg(feature = "global_jit_alloc")]
        impl<B: FnPtr, S: ?Sized> $ty_name<B, S, GlobalJitAlloc> {
            /// Wraps `fun`, producing a bare function of signature `B`.
            ///
            /// This constructor is best used when the type of `B` is already known from an existing
            /// type annotation. If you want to infer `B` from the closure arguments and a calling
            /// convention, consider using
            #[doc = $with_cc_doc]
            /// or the `new_*` suffixed constructors instead.
            ///
            /// The W^X memory required is allocated using the global JIT allocator.
            #[inline]
            pub fn new<F>(fun: F) -> Self
            where
                F: ToBoxedDyn<S>,
                (B::CC, F): $trait_ident<B>,
            {
                Self::new_in(fun, Default::default())
            }

            /// Wraps `fun`, producing a bare function with calling convention `cconv`.
            ///
            /// The W^X memory required is allocated using the global JIT allocator.
            #[inline]
            pub fn with_cc<CC, F>(cconv: CC, fun: F) -> Self
            where
                F: ToBoxedDyn<S>,
                (CC, F): $trait_ident<B>,
            {
                Self::with_cc_in(cconv, fun, Default::default())
            }

            /// Create a
            #[doc = $ty_name_doc]
            /// directly from a
            #[doc = concat!("[`", stringify!($trait_ident), "`].")]
            ///
            /// The W^X memory required is allocated using the global JIT allocator.
            pub fn with_thunk<T>(thunk: T) -> Self where T: $trait_ident<B> + ToBoxedDyn<S>
            {
                Self::with_thunk_in(thunk, Default::default())
            }
        }

        impl<B: FnPtr, S: ?Sized, A: JitAlloc> $ty_name<B, S, A> {
            #[$bare_toggle]
            /// Return a bare function pointer that invokes the underlying closure.
            ///
            /// # Safety
            /// While this method is safe, the returned function pointer is not. In particular, it
            /// must not be called when:
            /// - The lifetime of `self` has expired, or `self` has been dropped.
            #[doc = $safety_doc]
            #[inline]
            pub fn bare(self: $bare_receiver) -> B {
                // SAFETY: B is a bare function pointer
                unsafe { B::from_ptr(self.untyped.bare()) }
            }

            /// Leak the underlying closure, returning the unsafe bare function pointer that invokes
            /// it.
            ///
            /// `self` must be `'static` for this method to be called.
            ///
            /// # Safety
            /// While this method is safe, the returned function pointer is not. In particular, it
            /// must not be called when:
            #[doc = $safety_doc]
            #[inline]
            pub fn leak(self) -> B
            where
                Self: 'static,
            {
                // SAFETY: B is a bare function pointer
                unsafe { B::from_ptr(self.untyped.leak()) }
            }

            /// Erase the signature type from this
            #[doc = $ty_name_doc]
            ///
            /// The returned value also exposes the `bare` and `leak` functions.
            /// However, they now return untyped pointers.
            pub fn into_untyped(self) -> $erased_ty_name<S, A> {
                self.untyped
            }

            /// Weaken the bounds of the type-erased storage.
            ///
            /// For example, a [`BareFnAny<B, dyn Send + Sync>`] may be upcast into a [`BareFnAny<B, dyn Send>`].
            pub fn upcast<U: ?Sized>(self) -> $ty_name<B, U, A>
                where PhantomData<S>: ToBoxedDyn<U>,
            {
                // SAFETY: This is fine on stable since all trait objects implementing `ToBoxedDyn`
                // only have the destructor in their vtable.
                //
                // With the `unstable` feature, it's sketchy as a boxed `dyn Subtrait` can `Unsize` into
                // a `dyn Supertrait` when `Subtrait: Supertrait`. However, the undocumented layout of
                // trait object vtables makes the destructor the first entry, so it's fine for now
                // (and the foreseeable future).
                unsafe { core::mem::transmute_copy(&ManuallyDrop::new(self)) }
            }

            /// Wraps `fun`, producing a bare function with calling convention `cconv`.
            ///
            /// Uses the provided JIT allocator to allocate the W^X memory used to create the thunk.
            #[allow(unused_variables)]
            pub fn try_with_cc_in<CC, F>(
                cconv: CC,
                fun: F,
                jit_alloc: A,
            ) -> Result<Self, JitAllocError>
            where
                F: ToBoxedDyn<S>,
                (CC, F): $trait_ident<B>,
            {
                let storage = Box::into_raw(F::to_boxed_unsize(fun));

                // SAFETY:
                // - thunk_template pointer obtained from the correct source
                // - `closure` is a valid pointer to `fun`
                let thunk = unsafe {
                    AllocatedThunk::new(
                        <(CC, F)>::$thunk_template,
                        storage as *const _, size_of::<F>(),
                        jit_alloc
                    )?
                };
                Ok(Self {
                    untyped: $erased_ty_name {
                        thunk,
                        storage
                    },
                    phantom: PhantomData,
                })
            }

            /// Wraps `fun`, producing a bare function with calling convention `cconv`.
            ///
            /// Uses `jit_alloc` to allocate the W^X memory used to create the thunk.
            ///
            /// # Panics
            /// If the provided JIT allocator fails to allocate memory. For a non-panicking
            /// version, see
            #[doc = $try_with_cc_in_doc]
            #[allow(unused_variables)]
            #[inline]
            pub fn with_cc_in<CC, F>(cconv: CC, fun: F, jit_alloc: A) -> Self
            where
                F: ToBoxedDyn<S>,
                (CC, F): $trait_ident<B>,
            {
                Self::try_with_cc_in(cconv, fun, jit_alloc).unwrap()
            }

            /// Wraps `fun`, producing a bare function with signature `B`.
            ///
            /// Uses `jit_alloc` to allocate the W^X memory used to create the thunk.
            ///
            /// This constructor is best used when the type of `B` is already known from an existing
            /// type annotation. If you want to infer `B` from the closure arguments and a calling
            /// convention, consider using
            #[doc = $with_cc_in_doc]
            /// instead.
            ///
            /// # Panics
            /// If the provided JIT allocator fails to allocate memory. For a non-panicking
            /// version, see
            #[doc = $try_with_cc_in_doc]
            #[inline]
            pub fn new_in<F>(fun: F, jit_alloc: A) -> Self
            where
                F: ToBoxedDyn<S>,
                (B::CC, F): $trait_ident<B>,
            {
                Self::with_cc_in(B::CC::default(), fun, jit_alloc)
            }

            /// Create a
            #[doc = $ty_name_doc]
            /// directly from a
            #[doc = concat!("[`", stringify!($trait_ident), "`].")]
            ///
            /// Uses `jit_alloc` to allocate the W^X memory used to create the thunk.
            pub fn try_with_thunk_in<T>(thunk: T, jit_alloc: A) -> Result<Self, JitAllocError>
            where T: $trait_ident<B> + ToBoxedDyn<S>
            {
                // SAFETY: All implementors of `Fn*Thunk` are #[repr(transparent)] with the closure
                let storage = Box::into_raw(T::to_boxed_unsize(thunk));

                // SAFETY:
                // - thunk_template pointer obtained from the correct source
                // - `closure` is a valid pointer to `fun`
                // - `size_of::<T>()` equals the size of the closure
                let thunk = unsafe {
                    AllocatedThunk::new(
                        T::$thunk_template,
                        storage as *const _, size_of::<T>(),
                        jit_alloc
                    )?
                };
                Ok(Self {
                    untyped: $erased_ty_name {
                        thunk,
                        storage
                    },
                    phantom: PhantomData,
                })
            }

            /// Create a
            #[doc = $ty_name_doc]
            /// directly from a
            #[doc = concat!("[`", stringify!($trait_ident), "`].")]
            ///
            /// Uses `jit_alloc` to allocate the W^X memory used to create the thunk.
            ///
            /// # Panics
            /// If the provided JIT allocator fails to allocate memory. For a non-panicking
            /// version, see [`Self::try_with_thunk_in`].
            #[inline]
            pub fn with_thunk_in<T>(thunk: T, jit_alloc: A) -> Self
            where T: $trait_ident<B> + ToBoxedDyn<S>
            {
                Self::try_with_thunk_in(thunk, jit_alloc).unwrap()
            }
        }

        #[cfg(feature = "global_jit_alloc")]
        impl<B: FnPtr, S: ?Sized> $ty_name<B, S, GlobalJitAlloc> {
            cc_shorthand!(new_rust, $trait_ident, cc::Rust, "Rust");

            cc_shorthand!(new_c, $trait_ident, cc::C, "C");

            cc_shorthand!(new_system, $trait_ident, cc::System, "system");

            cc_shorthand!(new_efiabi, $trait_ident, cc::Efiapi, "efiapi");

            cc_shorthand!(
                new_sysv64,
                $trait_ident,
                cc::Sysv64,
                "sysv64",
                all(not(windows), target_arch = "x86_64")
            );

            cc_shorthand!(
                new_aapcs,
                $trait_ident,
                cc::Aapcs,
                "aapcs",
                any(doc, target_arch = "arm")
            );

            cc_shorthand!(
                new_fastcall,
                $trait_ident,
                cc::Fastcall,
                "fastcall",
                all(windows, target_arch = "x86")
            );

            cc_shorthand!(
                new_stdcall,
                $trait_ident,
                cc::Stdcall,
                "stdcall",
                all(windows, target_arch = "x86")
            );

            cc_shorthand!(
                new_cdecl,
                $trait_ident,
                cc::Cdecl,
                "cdecl",
                all(windows, target_arch = "x86")
            );

            cc_shorthand!(
                new_thiscall,
                $trait_ident,
                cc::Thiscall,
                "thiscall",
                all(windows, target_arch = "x86")
            );

            cc_shorthand!(
                new_win64,
                $trait_ident,
                cc::Win64,
                "win64",
                all(windows, target_arch = "x86_64")
            );

            cc_shorthand!(
                new_variadic,
                $trait_ident,
                cc::Variadic,
                "`C` variadic",
                feature = "c_variadic"
            );
        }

        impl<B: FnPtr, S: ?Sized, A: JitAlloc> $ty_name<B, S, A> {
            cc_shorthand_in!(new_rust_in, $trait_ident, cc::Rust, "Rust");

            cc_shorthand_in!(new_c_in, $trait_ident, cc::C, "C");

            cc_shorthand_in!(new_system_in, $trait_ident, cc::System, "system");

            cc_shorthand_in!(new_efiabi_in, $trait_ident, cc::Efiapi, "efiapi");

            cc_shorthand_in!(
                new_sysv64_in,
                $trait_ident,
                cc::Sysv64,
                "sysv64",
                all(not(windows), target_arch = "x86_64")
            );

            cc_shorthand_in!(
                new_aapcs_in,
                $trait_ident,
                cc::Aapcs,
                "aapcs",
                any(doc, target_arch = "arm")
            );

            cc_shorthand_in!(
                new_fastcall_in,
                $trait_ident,
                cc::Fastcall,
                "fastcall",
                all(windows, target_arch = "x86")
            );

            cc_shorthand_in!(
                new_stdcall_in,
                $trait_ident,
                cc::Stdcall,
                "stdcall",
                all(windows, target_arch = "x86")
            );

            cc_shorthand_in!(
                new_cdecl_in,
                $trait_ident,
                cc::Cdecl,
                "cdecl",
                all(windows, target_arch = "x86")
            );

            cc_shorthand_in!(
                new_thiscall_in,
                $trait_ident,
                cc::Thiscall,
                "thiscall",
                all(windows, target_arch = "x86")
            );

            cc_shorthand_in!(
                new_win64_in,
                $trait_ident,
                cc::Win64,
                "win64",
                all(windows, target_arch = "x86_64")
            );

            cc_shorthand_in!(
                new_variadic_in,
                $trait_ident,
                cc::Variadic,
                "`C` variadic",
                feature = "c_variadic"
            );
        }

        #[cfg(feature = "global_jit_alloc")]
        #[cfg_attr(docsrs, doc(cfg(all())))]
        /// Wrapper around a
        #[doc = $fn_trait_doc]
        /// closure which exposes a bare function thunk that can invoke it without
        /// additional arguments.
        ///
        /// This is a type alias only. Additional details and methods are described on the
        #[doc = $ty_name_doc]
        /// type.
        pub type $non_sync_alias<'a, B, A = GlobalJitAlloc> = $ty_name<B, dyn Any + 'a, A>;

        #[cfg(not(feature = "global_jit_alloc"))]
        /// Wrapper around a
        #[doc = $fn_trait_doc]
        /// closure which exposes a bare function thunk that can invoke it without
        /// additional arguments.
        ///
        /// This is a type alias only. Additional details and methods are described on the
        #[doc = $ty_name_doc]
        /// type.
        pub type $non_sync_alias<'a, B, A> = $ty_name<B, dyn Any + 'a, A>;

        #[cfg(feature = "global_jit_alloc")]
        #[cfg_attr(docsrs, doc(cfg(all())))]
        /// Wrapper around a
        #[doc = $fn_trait_doc]
        /// closure which exposes a bare function thunk that can invoke it without
        /// additional arguments.
        ///
        /// Unlike
        #[doc = $non_sync_alias_doc]
        /// this type enforces the correct combination of [`Send`] and [`Sync`] on the
        /// closure so that it is safe to both store and call from other threads.
        ///
        /// This is a type alias only. Additional details and methods are described on the
        #[doc = $ty_name_doc]
        /// type.
        pub type $sync_alias<'a, B, A = GlobalJitAlloc> = $ty_name<B, $sync_alias_bound, A>;

        #[cfg(not(feature = "global_jit_alloc"))]
        /// Wrapper around a
        #[doc = $fn_trait_doc]
        /// closure which exposes a bare function thunk that can invoke it without
        /// additional arguments.
        ///
        /// Unlike
        #[doc = $non_sync_alias_doc]
        /// this type enforces the correct combination of [`Send`] and [`Sync`] on the
        /// closure so that it is safe to both store and call from other threads.
        ///
        /// This is a type alias only. Additional details and methods are described on the
        #[doc = $ty_name_doc]
        /// type.
        pub type $sync_alias<'a, B, A> = $ty_name<B, $sync_alias_bound, A>;
    };
}

// TODO:
// BareFnOnce still needs work.
// In particular, to avoid leaks we need to have the compiler generated thunk
// call `release` on the allocator after it's done running, then drop the allocator.
// Then, to avoid double frees we need `bare` to be taken by value.
//
// At the moment, we simply force leaking for `BareFnOnce` by omitting `bare()`.

bare_closure_impl!(
    ty_name: BareFnOnceAny,
    erased_ty_name: UntypedBareFnOnce,
    non_sync_alias: BareFnOnce,
    sync_alias: BareFnOnceSync,
    sync_bounds: (Send), // FnOnce only needs to be Send
    sync_alias_bound: dyn Send + 'a,
    trait_ident: FnOnceThunk,
    thunk_template: THUNK_TEMPLATE_ONCE,
    bare_toggle: cfg(any()),
    bare_receiver: Self,
    fn_trait_doc: "[`FnOnce`]",
    ty_name_doc: "[`BareFnOnceAny`]",
    with_cc_doc: "[`with_cc`](BareFnOnceAny::with_cc)",
    with_cc_in_doc: "[`with_cc_in`](BareFnOnceAny::with_cc_in)",
    try_with_cc_in_doc: "[`try_with_cc_in`](BareFnOnceAny::try_with_cc_in)",
    non_sync_alias_doc: "[`BareFnOnce`]",
    sync_alias_doc: "[`BareFnOnceSync`]",
    sync_alias_bound_doc: "[`S = dyn Send + 'a`](Send)",
    safety_doc: "- The function has been called before.\n
- The closure is not `Send`, if calling from a different thread than the current one."
);

bare_closure_impl!(
    ty_name: BareFnMutAny,
    erased_ty_name: UntypedBareFnMut,
    non_sync_alias: BareFnMut,
    sync_alias: BareFnMutSync,
    sync_bounds: (Send), // For FnMut we only need Send to make synchronized calls safe
    sync_alias_bound: dyn Send + 'a,
    trait_ident: FnMutThunk,
    thunk_template: THUNK_TEMPLATE_MUT,
    bare_toggle: cfg(all()),
    bare_receiver: &Self,
    fn_trait_doc: "[`FnMut`]",
    ty_name_doc: "[`BareFnMutAny`]",
    with_cc_doc: "[`with_cc`](BareFnMutAny::with_cc)",
    with_cc_in_doc: "[`with_cc_in`](BareFnMutAny::with_cc_in)",
    try_with_cc_in_doc: "[`try_with_cc_in`](BareFnMutAny::try_with_cc_in)",
    non_sync_alias_doc:  "[`BareFnMut`]",
    sync_alias_doc: "[`BareFnMutSync`]",
    sync_alias_bound_doc: "[`S = dyn Send + 'a`](Send)",
    safety_doc: "- The mutable borrow induced by a previous call is still active (e.g. through recursion)
  or concurrent (has no happens-before relationship) with the current one.\n
- The closure is not `Send`, if calling from a different thread than the current one."
);
bare_closure_impl!(
    ty_name: BareFnAny,
    erased_ty_name: UntypedBareFn,
    non_sync_alias: BareFn,
    sync_alias: BareFnSync,
    sync_bounds: (Sync),
    sync_alias_bound: dyn Send + Sync + 'a,
    trait_ident: FnThunk,
    thunk_template: THUNK_TEMPLATE,
    bare_toggle: cfg(all()),
    bare_receiver: &Self,
    fn_trait_doc: "[`Fn`]",
    ty_name_doc: "[`BareFnAny`]",
    with_cc_doc: "[`with_cc`](BareFnAny::with_cc)",
    with_cc_in_doc: "[`with_cc_in`](BareFnAny::with_cc_in)",
    try_with_cc_in_doc: "[`try_with_cc_in`](BareFnAny::try_with_cc_in)",
    non_sync_alias_doc:  "[`BareFn`]",
    sync_alias_doc: "[`BareFnSync`]",
    sync_alias_bound_doc: "[`S = dyn Send + Sync + 'a`](Sync)",
    safety_doc: "- The closure is not `Sync`, if calling from a different thread than the current one."
);