Struct 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<F>(f: F) -> Self

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

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_async_fn.

Examples

async fn test(
    _this: &JsValue,
    args: &[JsValue],
    context: &RefCell<&mut Context>,
) -> JsResult<JsValue> {
    let arg = args.get_or_undefined(0).clone();
    std::future::ready(()).await;
    let value = arg.to_u32(&mut context.borrow_mut())?;
    Ok(JsValue::from(value * 2))
}
NativeFunction::from_async_fn(test);

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 duplicate 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.