mirror of https://github.com/boa-dev/boa.git
Browse Source
This PR is a complete redesign of our current native functions and closures API.
I was a bit dissatisfied with our previous design (even though I created it 😆), because it had a lot of superfluous traits, a forced usage of `Gc<GcCell<T>>` and an overly restrictive `NativeObject` bound. This redesign, on the other hand, simplifies a lot our public API, with a simple `NativeCallable` struct that has several constructors for each type of required native function.
This new design doesn't require wrapping every capture type with `Gc<GcCell<T>>`, relaxes the trait requirement to `Trace + 'static` for captures, can be reused in both `JsObject` functions and (soonish) host defined functions, and is (in my opinion) a bit cleaner than the previous iteration. It also offers an `unsafe` API as an escape hatch for users that want to pass non-Copy closures which don't capture traceable types.
Would ask for bikeshedding about the names though, because I don't know if `NativeCallable` is the most precise name for this. Same about the constructor names; I added the `from` prefix to all of them because it's the "standard" practice, but seeing the API doesn't have any other method aside from `call`, it may be better to just remove the prefix altogether.
Let me know what you think :)
pull/2524/head
José Julián Espina
2 years ago
46 changed files with 1897 additions and 1486 deletions
@ -0,0 +1,365 @@ |
|||||||
|
//! Boa's wrappers for native Rust functions to be compatible with ECMAScript calls.
|
||||||
|
//!
|
||||||
|
//! [`NativeFunction`] is the main type of this module, providing APIs to create native callables
|
||||||
|
//! from native Rust functions and closures.
|
||||||
|
|
||||||
|
use std::marker::PhantomData; |
||||||
|
|
||||||
|
use boa_gc::{custom_trace, Finalize, Gc, Trace}; |
||||||
|
|
||||||
|
use crate::{Context, JsResult, JsValue}; |
||||||
|
|
||||||
|
/// The required signature for all native built-in function pointers.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// - The first argument represents the `this` variable of every ECMAScript function.
|
||||||
|
///
|
||||||
|
/// - The second argument represents the list of all arguments passed to the function.
|
||||||
|
///
|
||||||
|
/// - The last argument is the engine [`Context`].
|
||||||
|
pub type NativeFunctionPointer = fn(&JsValue, &[JsValue], &mut Context<'_>) -> JsResult<JsValue>; |
||||||
|
|
||||||
|
trait TraceableClosure: Trace { |
||||||
|
fn call( |
||||||
|
&self, |
||||||
|
this: &JsValue, |
||||||
|
args: &[JsValue], |
||||||
|
context: &mut Context<'_>, |
||||||
|
) -> JsResult<JsValue>; |
||||||
|
} |
||||||
|
|
||||||
|
#[derive(Trace, Finalize)] |
||||||
|
struct Closure<F, T> |
||||||
|
where |
||||||
|
F: Fn(&JsValue, &[JsValue], &T, &mut Context<'_>) -> JsResult<JsValue>, |
||||||
|
T: Trace, |
||||||
|
{ |
||||||
|
// SAFETY: `NativeFunction`'s safe API ensures only `Copy` closures are stored; its unsafe API,
|
||||||
|
// on the other hand, explains the invariants to hold in order for this to be safe, shifting
|
||||||
|
// the responsibility to the caller.
|
||||||
|
#[unsafe_ignore_trace] |
||||||
|
f: F, |
||||||
|
captures: T, |
||||||
|
} |
||||||
|
|
||||||
|
impl<F, T> TraceableClosure for Closure<F, T> |
||||||
|
where |
||||||
|
F: Fn(&JsValue, &[JsValue], &T, &mut Context<'_>) -> JsResult<JsValue>, |
||||||
|
T: Trace, |
||||||
|
{ |
||||||
|
fn call( |
||||||
|
&self, |
||||||
|
this: &JsValue, |
||||||
|
args: &[JsValue], |
||||||
|
context: &mut Context<'_>, |
||||||
|
) -> JsResult<JsValue> { |
||||||
|
(self.f)(this, args, &self.captures, context) |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// A callable Rust function that can be invoked by the engine.
|
||||||
|
///
|
||||||
|
/// `NativeFunction` functions are divided in two:
|
||||||
|
/// - Function pointers a.k.a common functions (see [`NativeFunctionPointer`]).
|
||||||
|
/// - Closure functions that can capture the current environment.
|
||||||
|
///
|
||||||
|
/// # Caveats
|
||||||
|
///
|
||||||
|
/// By limitations of the Rust language, the garbage collector currently cannot inspect closures
|
||||||
|
/// in order to trace their captured variables. This means that only [`Copy`] closures are 100% safe
|
||||||
|
/// to use. All other closures can also be stored in a `NativeFunction`, albeit by using an `unsafe`
|
||||||
|
/// API, but note that passing closures implicitly capturing traceable types could cause
|
||||||
|
/// **Undefined Behaviour**.
|
||||||
|
#[derive(Clone)] |
||||||
|
pub struct NativeFunction { |
||||||
|
inner: Inner, |
||||||
|
} |
||||||
|
|
||||||
|
#[derive(Clone)] |
||||||
|
enum Inner { |
||||||
|
PointerFn(NativeFunctionPointer), |
||||||
|
Closure(Gc<dyn TraceableClosure>), |
||||||
|
} |
||||||
|
|
||||||
|
impl Finalize for NativeFunction { |
||||||
|
fn finalize(&self) { |
||||||
|
if let Inner::Closure(c) = &self.inner { |
||||||
|
c.finalize(); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
// Manual implementation because deriving `Trace` triggers the `single_use_lifetimes` lint.
|
||||||
|
// SAFETY: Only closures can contain `Trace` captures, so this implementation is safe.
|
||||||
|
unsafe impl Trace for NativeFunction { |
||||||
|
custom_trace!(this, { |
||||||
|
if let Inner::Closure(c) = &this.inner { |
||||||
|
mark(c); |
||||||
|
} |
||||||
|
}); |
||||||
|
} |
||||||
|
|
||||||
|
impl std::fmt::Debug for NativeFunction { |
||||||
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { |
||||||
|
f.debug_struct("NativeFunction").finish_non_exhaustive() |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
impl NativeFunction { |
||||||
|
/// Creates a `NativeFunction` from a function pointer.
|
||||||
|
#[inline] |
||||||
|
pub fn from_fn_ptr(function: NativeFunctionPointer) -> Self { |
||||||
|
Self { |
||||||
|
inner: Inner::PointerFn(function), |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// Creates a `NativeFunction` from a `Copy` closure.
|
||||||
|
pub fn from_copy_closure<F>(closure: F) -> Self |
||||||
|
where |
||||||
|
F: Fn(&JsValue, &[JsValue], &mut Context<'_>) -> JsResult<JsValue> + Copy + 'static, |
||||||
|
{ |
||||||
|
// SAFETY: The `Copy` bound ensures there are no traceable types inside the closure.
|
||||||
|
unsafe { Self::from_closure(closure) } |
||||||
|
} |
||||||
|
|
||||||
|
/// Creates a `NativeFunction` from a `Copy` closure and a list of traceable captures.
|
||||||
|
pub fn from_copy_closure_with_captures<F, T>(closure: F, captures: T) -> Self |
||||||
|
where |
||||||
|
F: Fn(&JsValue, &[JsValue], &T, &mut Context<'_>) -> JsResult<JsValue> + Copy + 'static, |
||||||
|
T: Trace + 'static, |
||||||
|
{ |
||||||
|
// SAFETY: The `Copy` bound ensures there are no traceable types inside the closure.
|
||||||
|
unsafe { Self::from_closure_with_captures(closure, captures) } |
||||||
|
} |
||||||
|
|
||||||
|
/// Creates a new `NativeFunction` from a closure.
|
||||||
|
///
|
||||||
|
/// # Safety
|
||||||
|
///
|
||||||
|
/// Passing a closure that contains a captured variable that needs to be traced by the garbage
|
||||||
|
/// collector could cause an use after free, memory corruption or other kinds of **Undefined
|
||||||
|
/// Behaviour**. See <https://github.com/Manishearth/rust-gc/issues/50> for a technical explanation
|
||||||
|
/// on why that is the case.
|
||||||
|
pub unsafe fn from_closure<F>(closure: F) -> Self |
||||||
|
where |
||||||
|
F: Fn(&JsValue, &[JsValue], &mut Context<'_>) -> JsResult<JsValue> + 'static, |
||||||
|
{ |
||||||
|
// SAFETY: The caller must ensure the invariants of the closure hold.
|
||||||
|
unsafe { |
||||||
|
Self::from_closure_with_captures( |
||||||
|
move |this, args, _, context| closure(this, args, context), |
||||||
|
(), |
||||||
|
) |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// Create a new `NativeFunction` from a closure and a list of traceable captures.
|
||||||
|
///
|
||||||
|
/// # Safety
|
||||||
|
///
|
||||||
|
/// Passing a closure that contains a captured variable that needs to be traced by the garbage
|
||||||
|
/// collector could cause an use after free, memory corruption or other kinds of **Undefined
|
||||||
|
/// Behaviour**. See <https://github.com/Manishearth/rust-gc/issues/50> for a technical explanation
|
||||||
|
/// on why that is the case.
|
||||||
|
pub unsafe fn from_closure_with_captures<F, T>(closure: F, captures: T) -> Self |
||||||
|
where |
||||||
|
F: Fn(&JsValue, &[JsValue], &T, &mut Context<'_>) -> JsResult<JsValue> + 'static, |
||||||
|
T: Trace + 'static, |
||||||
|
{ |
||||||
|
// Hopefully, this unsafe operation will be replaced by the `CoerceUnsized` API in the
|
||||||
|
// future: https://github.com/rust-lang/rust/issues/18598
|
||||||
|
let ptr = Gc::into_raw(Gc::new(Closure { |
||||||
|
f: closure, |
||||||
|
captures, |
||||||
|
})); |
||||||
|
// SAFETY: The pointer returned by `into_raw` is only used to coerce to a trait object,
|
||||||
|
// meaning this is safe.
|
||||||
|
unsafe { |
||||||
|
Self { |
||||||
|
inner: Inner::Closure(Gc::from_raw(ptr)), |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// Calls this `NativeFunction`, forwarding the arguments to the corresponding function.
|
||||||
|
#[inline] |
||||||
|
pub fn call( |
||||||
|
&self, |
||||||
|
this: &JsValue, |
||||||
|
args: &[JsValue], |
||||||
|
context: &mut Context<'_>, |
||||||
|
) -> JsResult<JsValue> { |
||||||
|
match self.inner { |
||||||
|
Inner::PointerFn(f) => f(this, args, context), |
||||||
|
Inner::Closure(ref c) => c.call(this, args, context), |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
trait TraceableGenericClosure<Ret, Args>: Trace { |
||||||
|
fn call(&mut self, args: Args, context: &mut Context<'_>) -> Ret; |
||||||
|
} |
||||||
|
|
||||||
|
#[derive(Trace, Finalize)] |
||||||
|
struct GenericClosure<Ret, Args, F, T> |
||||||
|
where |
||||||
|
F: FnMut(Args, &mut T, &mut Context<'_>) -> Ret, |
||||||
|
T: Trace, |
||||||
|
{ |
||||||
|
// SAFETY: `GenericNativeFunction`'s safe API ensures only `Copy` closures are stored; its unsafe API,
|
||||||
|
// on the other hand, explains the invariants to hold in order for this to be safe, shifting
|
||||||
|
// the responsibility to the caller.
|
||||||
|
#[unsafe_ignore_trace] |
||||||
|
f: F, |
||||||
|
captures: T, |
||||||
|
#[allow(clippy::type_complexity)] |
||||||
|
phantom: PhantomData<Box<dyn FnMut(Args, &mut T, &mut Context<'_>) -> Ret>>, |
||||||
|
} |
||||||
|
|
||||||
|
impl<Ret, Args, F, T> TraceableGenericClosure<Ret, Args> for GenericClosure<Ret, Args, F, T> |
||||||
|
where |
||||||
|
F: FnMut(Args, &mut T, &mut Context<'_>) -> Ret, |
||||||
|
T: Trace, |
||||||
|
{ |
||||||
|
fn call(&mut self, args: Args, context: &mut Context<'_>) -> Ret { |
||||||
|
(self.f)(args, &mut self.captures, context) |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// A callable generic Rust function that can be invoked by the engine.
|
||||||
|
///
|
||||||
|
/// This is a more general struct of the [`NativeFunction`] API, useful for callbacks defined in the
|
||||||
|
/// host that are useful to the engine, such as [`HostCallJobCallback`] or [`HostEnqueuePromiseJob`].
|
||||||
|
///
|
||||||
|
/// `GenericNativeFunction` functions are divided in two:
|
||||||
|
/// - Function pointers a.k.a common functions.
|
||||||
|
/// - Closure functions that can capture the current environment.
|
||||||
|
///
|
||||||
|
/// # Caveats
|
||||||
|
///
|
||||||
|
/// - Since the Rust language doesn't support [**variadic generics**], all functions requiring
|
||||||
|
/// more than 1 argument (excluding the required [`Context`]), will define its generic parameter
|
||||||
|
/// `Args` as a tuple instead, which slightly worsens the API. We hope this can improve when
|
||||||
|
/// variadic generics arrive.
|
||||||
|
///
|
||||||
|
/// - By limitations of the Rust language, the garbage collector currently cannot inspect closures
|
||||||
|
/// in order to trace their captured variables. This means that only [`Copy`] closures are 100% safe
|
||||||
|
/// to use. All other closures can also be stored in a `GenericNativeFunction`, albeit by using an
|
||||||
|
/// `unsafe` API, but note that passing closures implicitly capturing traceable types could cause
|
||||||
|
/// **Undefined Behaviour**.
|
||||||
|
///
|
||||||
|
/// [`HostCallJobCallback`]: https://tc39.es/ecma262/#sec-hostcalljobcallback
|
||||||
|
/// [`HostEnqueuePromiseJob`]: https://tc39.es/ecma262/#sec-hostenqueuepromisejob
|
||||||
|
/// [**variadic generics**]: https://github.com/rust-lang/rfcs/issues/376
|
||||||
|
pub struct GenericNativeFunction<Ret: 'static, Args: 'static> { |
||||||
|
inner: GenericInner<Ret, Args>, |
||||||
|
} |
||||||
|
|
||||||
|
enum GenericInner<Ret: 'static, Args: 'static> { |
||||||
|
PointerFn(fn(Args, &mut Context<'_>) -> Ret), |
||||||
|
Closure(Box<dyn TraceableGenericClosure<Ret, Args>>), |
||||||
|
} |
||||||
|
|
||||||
|
impl<Ret, Args> Finalize for GenericNativeFunction<Ret, Args> { |
||||||
|
fn finalize(&self) { |
||||||
|
if let GenericInner::Closure(c) = &self.inner { |
||||||
|
c.finalize(); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
// Manual implementation because deriving `Trace` triggers the `single_use_lifetimes` lint.
|
||||||
|
// SAFETY: Only closures can contain `Trace` captures, so this implementation is safe.
|
||||||
|
unsafe impl<Ret, Args> Trace for GenericNativeFunction<Ret, Args> { |
||||||
|
custom_trace!(this, { |
||||||
|
if let GenericInner::Closure(c) = &this.inner { |
||||||
|
mark(c); |
||||||
|
} |
||||||
|
}); |
||||||
|
} |
||||||
|
|
||||||
|
impl<Ret, Args> std::fmt::Debug for GenericNativeFunction<Ret, Args> { |
||||||
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { |
||||||
|
f.debug_struct("NativeFunction").finish_non_exhaustive() |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
impl<Ret, Args> GenericNativeFunction<Ret, Args> { |
||||||
|
/// Creates a `GenericNativeFunction` from a function pointer.
|
||||||
|
#[inline] |
||||||
|
pub fn from_fn_ptr(function: fn(Args, &mut Context<'_>) -> Ret) -> Self { |
||||||
|
Self { |
||||||
|
inner: GenericInner::PointerFn(function), |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// Creates a `GenericNativeFunction` from a `Copy` closure.
|
||||||
|
pub fn from_copy_closure<F>(closure: F) -> Self |
||||||
|
where |
||||||
|
F: FnMut(Args, &mut Context<'_>) -> Ret + Copy + 'static, |
||||||
|
{ |
||||||
|
// SAFETY: The `Copy` bound ensures there are no traceable types inside the closure.
|
||||||
|
unsafe { Self::from_closure(closure) } |
||||||
|
} |
||||||
|
|
||||||
|
/// Creates a `GenericNativeFunction` from a `Copy` closure and a list of traceable captures.
|
||||||
|
pub fn from_copy_closure_with_captures<F, T>(closure: F, captures: T) -> Self |
||||||
|
where |
||||||
|
F: FnMut(Args, &mut T, &mut Context<'_>) -> Ret + Copy + 'static, |
||||||
|
T: Trace + 'static, |
||||||
|
{ |
||||||
|
// SAFETY: The `Copy` bound ensures there are no traceable types inside the closure.
|
||||||
|
unsafe { Self::from_closure_with_captures(closure, captures) } |
||||||
|
} |
||||||
|
|
||||||
|
/// Creates a new `GenericNativeFunction` from a closure.
|
||||||
|
///
|
||||||
|
/// # Safety
|
||||||
|
///
|
||||||
|
/// Passing a closure that contains a captured variable that needs to be traced by the garbage
|
||||||
|
/// collector could cause an use after free, memory corruption or other kinds of **Undefined
|
||||||
|
/// Behaviour**. See <https://github.com/Manishearth/rust-gc/issues/50> for a technical explanation
|
||||||
|
/// on why that is the case.
|
||||||
|
pub unsafe fn from_closure<F>(mut closure: F) -> Self |
||||||
|
where |
||||||
|
F: FnMut(Args, &mut Context<'_>) -> Ret + 'static, |
||||||
|
{ |
||||||
|
// SAFETY: The caller must ensure the invariants of the closure hold.
|
||||||
|
unsafe { |
||||||
|
Self::from_closure_with_captures(move |args, _, context| closure(args, context), ()) |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// Create a new `GenericNativeFunction` from a closure and a list of traceable captures.
|
||||||
|
///
|
||||||
|
/// # Safety
|
||||||
|
///
|
||||||
|
/// Passing a closure that contains a captured variable that needs to be traced by the garbage
|
||||||
|
/// collector could cause an use after free, memory corruption or other kinds of **Undefined
|
||||||
|
/// Behaviour**. See <https://github.com/Manishearth/rust-gc/issues/50> for a technical explanation
|
||||||
|
/// on why that is the case.
|
||||||
|
pub unsafe fn from_closure_with_captures<F, T>(closure: F, captures: T) -> Self |
||||||
|
where |
||||||
|
F: FnMut(Args, &mut T, &mut Context<'_>) -> Ret + 'static, |
||||||
|
T: Trace + 'static, |
||||||
|
{ |
||||||
|
Self { |
||||||
|
inner: GenericInner::Closure(Box::new(GenericClosure { |
||||||
|
f: closure, |
||||||
|
captures, |
||||||
|
phantom: PhantomData, |
||||||
|
})), |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// Calls this `GenericNativeFunction`, forwarding the arguments to the corresponding function.
|
||||||
|
#[inline] |
||||||
|
pub fn call(&mut self, args: Args, context: &mut Context<'_>) -> Ret { |
||||||
|
match self.inner { |
||||||
|
GenericInner::PointerFn(f) => f(args, context), |
||||||
|
GenericInner::Closure(ref mut c) => c.call(args, context), |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
@ -1,4 +1,5 @@ |
|||||||
mod ephemeron_box; |
mod ephemeron_box; |
||||||
mod gc_box; |
mod gc_box; |
||||||
|
|
||||||
pub(crate) use self::{ephemeron_box::EphemeronBox, gc_box::GcBox}; |
pub(crate) use self::ephemeron_box::EphemeronBox; |
||||||
|
pub use self::gc_box::GcBox; |
||||||
|
|||||||
Loading…
Reference in new issue