Trait Context

pub trait Context<'a>: ContextInternal<'a> {
    // Provided methods
    fn lock<'b>(&'b mut self) -> Lock<'b, Self>
       where 'a: 'b { ... }
    fn execute_scoped<'b, T, F>(&mut self, f: F) -> T
       where F: FnOnce(Cx<'b>) -> T,
             'a: 'b { ... }
    fn compute_scoped<'b, V, F>(&mut self, f: F) -> JsResult<'a, V>
       where V: Value,
             F: FnOnce(Cx<'b>) -> JsResult<'b, V>,
             'a: 'b { ... }
    fn try_catch<T, F>(&mut self, f: F) -> Result<T, Handle<'a, JsValue>>
       where F: FnOnce(&mut Self) -> NeonResult<T> { ... }
    fn boolean(&mut self, b: bool) -> Handle<'a, JsBoolean> { ... }
    fn number<T: Into<f64>>(&mut self, x: T) -> Handle<'a, JsNumber> { ... }
    fn string<S: AsRef<str>>(&mut self, s: S) -> Handle<'a, JsString> { ... }
    fn try_string<S: AsRef<str>>(&mut self, s: S) -> StringResult<'a> { ... }
    fn null(&mut self) -> Handle<'a, JsNull> { ... }
    fn undefined(&mut self) -> Handle<'a, JsUndefined> { ... }
    fn empty_object(&mut self) -> Handle<'a, JsObject> { ... }
    fn empty_array(&mut self) -> Handle<'a, JsArray> { ... }
    fn array_buffer(&mut self, size: usize) -> JsResult<'a, JsArrayBuffer> { ... }
    fn buffer(&mut self, size: usize) -> JsResult<'a, JsBuffer> { ... }
    fn date(
        &mut self,
        value: impl Into<f64>,
    ) -> Result<Handle<'a, JsDate>, DateError> { ... }
    fn global<T: Value>(&mut self, name: &str) -> JsResult<'a, T> { ... }
    fn global_object(&mut self) -> Handle<'a, JsObject> { ... }
    fn throw<T: Value, U>(&mut self, v: Handle<'_, T>) -> NeonResult<U> { ... }
    fn error<S: AsRef<str>>(&mut self, msg: S) -> JsResult<'a, JsError> { ... }
    fn type_error<S: AsRef<str>>(&mut self, msg: S) -> JsResult<'a, JsError> { ... }
    fn range_error<S: AsRef<str>>(&mut self, msg: S) -> JsResult<'a, JsError> { ... }
    fn throw_error<S: AsRef<str>, T>(&mut self, msg: S) -> NeonResult<T> { ... }
    fn throw_type_error<S: AsRef<str>, T>(&mut self, msg: S) -> NeonResult<T> { ... }
    fn throw_range_error<S: AsRef<str>, T>(&mut self, msg: S) -> NeonResult<T> { ... }
    fn boxed<U: Finalize + 'static>(&mut self, v: U) -> Handle<'a, JsBox<U>> { ... }
    fn channel(&mut self) -> Channel { ... }
    fn promise(&mut self) -> (Deferred, Handle<'a, JsPromise>) { ... }
    fn task<'cx, O, E>(&'cx mut self, execute: E) -> TaskBuilder<'cx, Self, E>
       where O: Send + 'static,
             E: FnOnce() -> O + Send + 'static,
             'a: 'cx { ... }
    fn to_raw(&self) -> Env { ... }
}

An execution context, which represents the current state of a thread of execution in the JavaScript engine.

All interaction with the JavaScript engine in Neon code is mediated through instances of this trait.

A context has a lifetime 'a, which ensures the safety of handles managed by the JS garbage collector. All handles created during the lifetime of a context are kept alive for that duration and cannot outlive the context.

Provided Methods

fn lock<'b>(&'b mut self) -> Lock<'b, Self>

where 'a: 'b,

Lock the JavaScript engine, returning an RAII guard that keeps the lock active as long as the guard is alive.

If this is not the currently active context (for example, if it was used to spawn a scoped context with execute_scoped or compute_scoped), this method will panic.

fn execute_scoped<'b, T, F>(&mut self, f: F) -> T

where F: FnOnce(Cx<'b>) -> T, 'a: 'b,

Executes a computation in a new memory management scope.

Handles created in the new scope are kept alive only for the duration of the computation and cannot escape.

This method can be useful for limiting the life of temporary values created during long-running computations, to prevent leaks.

fn compute_scoped<'b, V, F>(&mut self, f: F) -> JsResult<'a, V>

where V: Value, F: FnOnce(Cx<'b>) -> JsResult<'b, V>, 'a: 'b,

Executes a computation in a new memory management scope and computes a single result value that outlives the computation.

Handles created in the new scope are kept alive only for the duration of the computation and cannot escape, with the exception of the result value, which is rooted in the outer context.

This method can be useful for limiting the life of temporary values created during long-running computations, to prevent leaks.

fn try_catch<T, F>(&mut self, f: F) -> Result<T, Handle<'a, JsValue>>

where F: FnOnce(&mut Self) -> NeonResult<T>,

fn boolean(&mut self, b: bool) -> Handle<'a, JsBoolean>

Convenience method for creating a JsBoolean value.

fn number<T: Into<f64>>(&mut self, x: T) -> Handle<'a, JsNumber>

Convenience method for creating a JsNumber value.

fn string<S: AsRef<str>>(&mut self, s: S) -> Handle<'a, JsString>

Convenience method for creating a JsString value.

If the string exceeds the limits of the JS engine, this method panics.

fn try_string<S: AsRef<str>>(&mut self, s: S) -> StringResult<'a>

Convenience method for creating a JsString value.

If the string exceeds the limits of the JS engine, this method returns an Err value.

fn null(&mut self) -> Handle<'a, JsNull>

Convenience method for creating a JsNull value.

fn undefined(&mut self) -> Handle<'a, JsUndefined>

Convenience method for creating a JsUndefined value.

fn empty_object(&mut self) -> Handle<'a, JsObject>

Convenience method for creating an empty JsObject value.

fn empty_array(&mut self) -> Handle<'a, JsArray>

Convenience method for creating an empty JsArray value.

fn array_buffer(&mut self, size: usize) -> JsResult<'a, JsArrayBuffer>

Convenience method for creating an empty JsArrayBuffer value.

fn buffer(&mut self, size: usize) -> JsResult<'a, JsBuffer>

Convenience method for creating an empty JsBuffer value.

fn date( &mut self, value: impl Into<f64>, ) -> Result<Handle<'a, JsDate>, DateError>

Available on crate feature napi-5 only.

Convenience method for creating a JsDate value.

fn global<T: Value>(&mut self, name: &str) -> JsResult<'a, T>

Convenience method for looking up a global property by name.

Equivalent to:

{
    let global = cx.global_object();
    global.prop(cx, name).get()
}

fn global_object(&mut self) -> Handle<'a, JsObject>

Produces a handle to the JavaScript global object.

fn throw<T: Value, U>(&mut self, v: Handle<'_, T>) -> NeonResult<U>

Throws a JS value.

fn error<S: AsRef<str>>(&mut self, msg: S) -> JsResult<'a, JsError>

Creates a direct instance of the Error class.

fn type_error<S: AsRef<str>>(&mut self, msg: S) -> JsResult<'a, JsError>

Creates an instance of the TypeError class.

fn range_error<S: AsRef<str>>(&mut self, msg: S) -> JsResult<'a, JsError>

Creates an instance of the RangeError class.

fn throw_error<S: AsRef<str>, T>(&mut self, msg: S) -> NeonResult<T>

Throws a direct instance of the Error class.

fn throw_type_error<S: AsRef<str>, T>(&mut self, msg: S) -> NeonResult<T>

Throws an instance of the TypeError class.

fn throw_range_error<S: AsRef<str>, T>(&mut self, msg: S) -> NeonResult<T>

Throws an instance of the RangeError class.

fn boxed<U: Finalize + 'static>(&mut self, v: U) -> Handle<'a, JsBox<U>>

Convenience method for wrapping a value in a JsBox.

Example:

struct Point(usize, usize);

impl Finalize for Point {}

fn my_neon_function(mut cx: FunctionContext) -> JsResult<JsBox<Point>> {
    let point = cx.boxed(Point(0, 1));

    Ok(point)
}

fn channel(&mut self) -> Channel

Available on crate feature napi-4 only.

Returns an unbounded channel for scheduling events to be executed on the JavaScript thread.

When using N-API >= 6,the channel returned by this method is backed by a shared queue. To create a channel backed by a new queue see Channel.

fn promise(&mut self) -> (Deferred, Handle<'a, JsPromise>)

Creates a Deferred and JsPromise pair. The Deferred handle can be used to resolve or reject the JsPromise.

fn resolve_promise(mut cx: FunctionContext) -> JsResult<JsPromise> {
    let (deferred, promise) = cx.promise();
    let msg = cx.string("Hello, World!");

    deferred.resolve(&mut cx, msg);

    Ok(promise)
}

fn task<'cx, O, E>(&'cx mut self, execute: E) -> TaskBuilder<'cx, Self, E>

where O: Send + 'static, E: FnOnce() -> O + Send + 'static, 'a: 'cx,

Creates a TaskBuilder which can be used to schedule the execute callback to asynchronously execute on the Node worker pool.

fn greet(mut cx: FunctionContext) -> JsResult<JsPromise> {
    let name = cx.argument::<JsString>(0)?.value(&mut cx);

    let promise = cx
        .task(move || format!("Hello, {}!", name))
        .promise(move |mut cx, greeting| Ok(cx.string(greeting)));

    Ok(promise)
}

fn to_raw(&self) -> Env

Available on crate feature sys only.

Gets the raw sys::Env for usage with Node-API.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'cx> Context<'cx> for Cx<'cx>

impl<'cx> Context<'cx> for FunctionContext<'cx>

impl<'cx> Context<'cx> for ModuleContext<'cx>