Struct boa_engine::native_function::NativeFunction
source · pub struct NativeFunction { /* private fields */ }
Expand description
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§
source§impl NativeFunction
impl NativeFunction
sourcepub fn from_fn_ptr(function: NativeFunctionPointer) -> Self
pub fn from_fn_ptr(function: NativeFunctionPointer) -> Self
Creates a NativeFunction
from a function pointer.
sourcepub fn from_async_fn<Fut>(
f: fn(_: &JsValue, _: &[JsValue], _: &mut Context) -> Fut
) -> Self
pub fn from_async_fn<Fut>( f: fn(_: &JsValue, _: &[JsValue], _: &mut Context) -> Fut ) -> Self
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.
sourcepub fn from_copy_closure<F>(closure: F) -> Self
pub fn from_copy_closure<F>(closure: F) -> Self
Creates a NativeFunction
from a Copy
closure.
sourcepub fn from_copy_closure_with_captures<F, T>(closure: F, captures: T) -> Self
pub fn from_copy_closure_with_captures<F, T>(closure: F, captures: T) -> Self
Creates a NativeFunction
from a Copy
closure and a list of traceable captures.
sourcepub unsafe fn from_closure<F>(closure: F) -> Self
pub unsafe fn from_closure<F>(closure: F) -> Self
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.
sourcepub unsafe fn from_closure_with_captures<F, T>(closure: F, captures: T) -> Self
pub unsafe fn from_closure_with_captures<F, T>(closure: F, captures: T) -> Self
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.
sourcepub fn call(
&self,
this: &JsValue,
args: &[JsValue],
context: &mut Context
) -> JsResult<JsValue>
pub fn call( &self, this: &JsValue, args: &[JsValue], context: &mut Context ) -> JsResult<JsValue>
Calls this NativeFunction
, forwarding the arguments to the corresponding function.
sourcepub fn to_js_function(self, realm: &Realm) -> JsFunction
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§
source§impl Clone for NativeFunction
impl Clone for NativeFunction
source§fn clone(&self) -> NativeFunction
fn clone(&self) -> NativeFunction
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for NativeFunction
impl Debug for NativeFunction
source§impl Trace for NativeFunction
impl Trace for NativeFunction
source§unsafe fn trace_non_roots(&self)
unsafe fn trace_non_roots(&self)
source§fn run_finalizer(&self)
fn run_finalizer(&self)
Finalize::finalize
on this object and all
contained subobjects.Auto Trait Implementations§
impl !RefUnwindSafe for NativeFunction
impl !Send for NativeFunction
impl !Sync for NativeFunction
impl Unpin for NativeFunction
impl !UnwindSafe for NativeFunction
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
source§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
source§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
self
and passes that borrow into the pipe function. Read moresource§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
self
and passes that borrow into the pipe function. Read moresource§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
source§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> R
source§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
self
, then passes self.as_ref()
into the pipe function.source§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
self
, then passes self.as_mut()
into the pipe
function.source§fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
self
, then passes self.deref()
into the pipe function.source§impl<T> Tap for T
impl<T> Tap for T
source§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B>
of a value. Read moresource§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B>
of a value. Read moresource§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R>
view of a value. Read moresource§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R>
view of a value. Read moresource§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target
of a value. Read moresource§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target
of a value. Read moresource§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap()
only in debug builds, and is erased in release builds.source§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut()
only in debug builds, and is erased in release
builds.source§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.tap_borrow()
only in debug builds, and is erased in release
builds.source§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
.tap_borrow_mut()
only in debug builds, and is erased in release
builds.source§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.tap_ref()
only in debug builds, and is erased in release
builds.source§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
.tap_ref_mut()
only in debug builds, and is erased in release
builds.source§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref()
only in debug builds, and is erased in release
builds.