Trait neon::context::Context

pub trait Context<'a>: ContextInternal<'a> {
    pub fn lock(&self) -> Lock<'_> { ... }
    pub fn borrow<'c, V, T, F>(&self, v: &'c Handle<'_, V>, f: F) -> T
    where
        V: Value,
        &'c V: Borrow,
        F: for<'b> FnOnce(Ref<'b, <&'c V as Borrow>::Target>) -> T,
    { ... }
    pub fn borrow_mut<'c, V, T, F>(&self, v: &'c mut Handle<'_, V>, f: F) -> T
    where
        V: Value,
        &'c mut V: BorrowMut,
        F: for<'b> FnOnce(RefMut<'b, <&'c mut V as Borrow>::Target>) -> T,
    { ... }
    pub fn execute_scoped<T, F>(&self, f: F) -> T
    where
        F: for<'b> FnOnce(ExecuteContext<'b>) -> T,
    { ... }
    pub fn compute_scoped<V, F>(&self, f: F) -> JsResult<'a, V>
    where
        V: Value,
        F: for<'b, 'c> FnOnce(ComputeContext<'b, 'c>) -> JsResult<'b, V>,
    { ... }
    pub fn try_catch<'b: 'a, T, F>(
        &mut self, 
        f: F
    ) -> Result<T, Handle<'a, JsValue>>
    where
        F: FnOnce(&mut Self) -> NeonResult<T>,
    { ... }
    pub fn boolean(&mut self, b: bool) -> Handle<'a, JsBoolean> { ... }
    pub fn number<T: Into<f64>>(&mut self, x: T) -> Handle<'a, JsNumber> { ... }
    pub fn string<S: AsRef<str>>(&mut self, s: S) -> Handle<'a, JsString> { ... }
    pub fn try_string<S: AsRef<str>>(&mut self, s: S) -> StringResult<'a> { ... }
    pub fn null(&mut self) -> Handle<'a, JsNull> { ... }
    pub fn undefined(&mut self) -> Handle<'a, JsUndefined> { ... }
    pub fn empty_object(&mut self) -> Handle<'a, JsObject> { ... }
    pub fn empty_array(&mut self) -> Handle<'a, JsArray> { ... }
    pub fn array_buffer(&mut self, size: u32) -> JsResult<'a, JsArrayBuffer> { ... }
    pub fn buffer(&mut self, size: u32) -> JsResult<'a, JsBuffer> { ... }
    pub fn global(&mut self) -> Handle<'a, JsObject> { ... }
    pub fn throw<'b, T: Value, U>(&mut self, v: Handle<'b, T>) -> NeonResult<U> { ... }
    pub fn error<S: AsRef<str>>(&mut self, msg: S) -> JsResult<'a, JsError> { ... }
    pub fn type_error<S: AsRef<str>>(&mut self, msg: S) -> JsResult<'a, JsError> { ... }
    pub fn range_error<S: AsRef<str>>(
        &mut self, 
        msg: S
    ) -> JsResult<'a, JsError> { ... }
    pub fn throw_error<S: AsRef<str>, T>(&mut self, msg: S) -> NeonResult<T> { ... }
    pub fn throw_type_error<S: AsRef<str>, T>(
        &mut self, 
        msg: S
    ) -> NeonResult<T> { ... }
    pub fn throw_range_error<S: AsRef<str>, T>(
        &mut self, 
        msg: S
    ) -> NeonResult<T> { ... }
}

An execution context, which provides context-sensitive access to the JavaScript engine. Most operations that interact with the engine require passing a reference to a context.

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

pub fn lock(&self) -> Lock<'_>

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.

pub fn borrow<'c, V, T, F>(&self, v: &'c Handle<'_, V>, f: F) -> T where
    V: Value,
    &'c V: Borrow,
    F: for<'b> FnOnce(Ref<'b, <&'c V as Borrow>::Target>) -> T, 

Convenience method for locking the JavaScript engine and borrowing a single JS value's internals.

Example:

let b: Handle<JsArrayBuffer> = cx.argument(0)?;
let x: u32 = cx.borrow(&b, |data| { data.as_slice()[0] });
let n: Handle<JsNumber> = cx.number(x);

Note: the borrowed value is required to be a reference to a handle instead of a handle as a workaround for a Rust compiler bug. We may be able to generalize this compatibly in the future when the Rust bug is fixed, but while the extra & is a small ergonomics regression, this API is still a nice convenience.

pub fn borrow_mut<'c, V, T, F>(&self, v: &'c mut Handle<'_, V>, f: F) -> T where
    V: Value,
    &'c mut V: BorrowMut,
    F: for<'b> FnOnce(RefMut<'b, <&'c mut V as Borrow>::Target>) -> T, 

Convenience method for locking the JavaScript engine and mutably borrowing a single JS value's internals.

Example:

let mut b: Handle<JsArrayBuffer> = cx.argument(0)?;
cx.borrow_mut(&mut b, |data| {
    let slice = data.as_mut_slice::<u32>();
    slice[0] += 1;
});

Note: the borrowed value is required to be a reference to a handle instead of a handle as a workaround for a Rust compiler bug. We may be able to generalize this compatibly in the future when the Rust bug is fixed, but while the extra &mut is a small ergonomics regression, this API is still a nice convenience.

pub fn execute_scoped<T, F>(&self, f: F) -> T where
    F: for<'b> FnOnce(ExecuteContext<'b>) -> T, 

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.

pub fn compute_scoped<V, F>(&self, f: F) -> JsResult<'a, V> where
    V: Value,
    F: for<'b, 'c> FnOnce(ComputeContext<'b, 'c>) -> JsResult<'b, V>, 

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.

pub fn try_catch<'b: 'a, T, F>(
    &mut self,
    f: F
) -> Result<T, Handle<'a, JsValue>> where
    F: FnOnce(&mut Self) -> NeonResult<T>, 

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

Convenience method for creating a JsBoolean value.

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

Convenience method for creating a JsNumber value.

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

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

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

Convenience method for creating a JsNull value.

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

Convenience method for creating a JsUndefined value.

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

Convenience method for creating an empty JsObject value.

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

Convenience method for creating an empty JsArray value.

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

Convenience method for creating an empty JsArrayBuffer value.

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

Convenience method for creating an empty JsBuffer value.

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

Produces a handle to the JavaScript global object.

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

Throws a JS value.

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

Creates a direct instance of the Error class.

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

Creates an instance of the TypeError class.

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

Creates an instance of the RangeError class.

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

Throws a direct instance of the Error class.

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

Throws an instance of the TypeError class.

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

Throws an instance of the RangeError class.

Loading content...

Implementors

impl<'a> Context<'a> for ExecuteContext<'a>

impl<'a> Context<'a> for ModuleContext<'a>

impl<'a> Context<'a> for TaskContext<'a>

impl<'a, 'b> Context<'a> for ComputeContext<'a, 'b>

impl<'a, T: This> Context<'a> for CallContext<'a, T>

Loading content...