Struct boa_engine::native_function::NativeFunction

pub struct NativeFunction { /* private fields */ }

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.

Implementations

impl NativeFunction

pub fn from_fn_ptr(function: NativeFunctionPointer) -> Self

Creates a NativeFunction from a function pointer.

pub fn from_async_fn<Fut>( f: fn(_: &JsValue, _: &[JsValue], _: &mut Context) -> Fut ) -> Self

where Fut: IntoFuture<Output = JsResult<JsValue>> + 'static,

Creates a NativeFunction from a function returning a Future-like.

The returned NativeFunction will return an ECMAScript Promise that will be fulfilled or rejected when the returned Future completes.

If you only need to convert a Future-like into a JsPromise, see JsPromise::from_future.

Caveats

Certain async functions need to be desugared for them to be 'static'. For example, the following won’t compile:

async fn test(
    _this: &JsValue,
    args: &[JsValue],
    _context: &mut Context,
) -> JsResult<JsValue> {
    let arg = args.get(0).cloned();
    std::future::ready(()).await;
    drop(arg);
    Ok(JsValue::null())
}
NativeFunction::from_async_fn(test);

Even though args is only used before the first await point, Rust’s async functions are fully lazy, which makes test equivalent to something like:

fn test<'a>(
    _this: &JsValue,
    args: &'a [JsValue],
    _context: &mut Context,
) -> impl Future<Output = JsResult<JsValue>> + 'a {
    async move {
        let arg = args.get(0).cloned();
        std::future::ready(()).await;
        drop(arg);
        Ok(JsValue::null())
    }
}

Note that args is used inside the async move, making the whole future not 'static.

In those cases, you can manually restrict the lifetime of the arguments:

fn test(
    _this: &JsValue,
    args: &[JsValue],
    _context: &mut Context,
) -> impl Future<Output = JsResult<JsValue>> {
    let arg = args.get(0).cloned();
    async move {
        std::future::ready(()).await;
        drop(arg);
        Ok(JsValue::null())
    }
}
NativeFunction::from_async_fn(test);

And this should always return a 'static future.

pub fn from_copy_closure<F>(closure: F) -> Self

where F: Fn(&JsValue, &[JsValue], &mut Context) -> JsResult<JsValue> + Copy + 'static,

Creates a NativeFunction from a Copy closure.

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,

Creates a NativeFunction from a Copy closure and a list of traceable captures.

pub unsafe fn from_closure<F>(closure: F) -> Self

where F: Fn(&JsValue, &[JsValue], &mut Context) -> JsResult<JsValue> + 'static,

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_with_captures<F, T>(closure: F, captures: T) -> Self

where F: Fn(&JsValue, &[JsValue], &T, &mut Context) -> JsResult<JsValue> + 'static, T: Trace + 'static,

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 fn call( &self, this: &JsValue, args: &[JsValue], context: &mut Context ) -> JsResult<JsValue>

Calls this NativeFunction, forwarding the arguments to the corresponding function.

pub fn to_js_function(self, realm: &Realm) -> JsFunction

Converts this NativeFunction into a JsFunction without setting its name or length.

Useful to create functions that will only be used once, such as callbacks.

Trait Implementations

impl Clone for NativeFunction

fn clone(&self) -> NativeFunction

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NativeFunction

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Finalize for NativeFunction

fn finalize(&self)

Cleanup logic for a type.

impl Trace for NativeFunction

unsafe fn trace(&self, tracer: &mut Tracer)

Marks all contained Gcs.

unsafe fn trace_non_roots(&self)

Trace handles located in GC heap, and mark them as non root.

fn run_finalizer(&self)

Runs Finalize::finalize on this object and all contained subobjects.