Struct Root

pub struct Root<T> { /* private fields */ }

A thread-safe handle that holds a reference to a JavaScript object and prevents it from being garbage collected.

A Root<T> may be sent across threads, but the referenced object may only be accessed on the JavaScript thread that created it.

Implementations

impl<T: Object> Root<T>

pub fn new<'a, C: Context<'a>>(cx: &mut C, value: &T) -> Self

Create a reference to a JavaScript object. The object will not be garbage collected until the Root is dropped. A Root<T> may only be dropped on the JavaScript thread that created it.

The caller should ensure Root::into_inner or Root::drop is called to properly dispose of the Root<T>. If the value is dropped without calling one of these methods:

• N-API < 6, Neon will panic to notify of the leak
• N-API >= 6, Neon will drop from a global queue at a runtime cost

pub fn clone<'a, C: Context<'a>>(&self, cx: &mut C) -> Self

Clone a reference to the contained JavaScript object. This method can be considered identical to the following:

let inner = root.into_inner(&mut cx);
let cloned = inner.root(&mut cx);
let root = inner.root(&mut cx);

pub fn drop<'a, C: Context<'a>>(self, cx: &mut C)

Safely drop a Root<T> without returning the referenced JavaScript object.

pub fn into_inner<'a, C: Context<'a>>(self, cx: &mut C) -> Handle<'a, T>

Return the referenced JavaScript object and allow it to be garbage collected.

Panics

This method panics if it is called from a different JavaScript thread than the one in which the handle was created.

pub fn to_inner<'a, C: Context<'a>>(&self, cx: &mut C) -> Handle<'a, T>

Access the inner JavaScript object without consuming the Root This method aliases the reference without changing the reference count. It can be used in place of a clone immediately followed by a call to into_inner.

Panics

This method panics if it is called from a different JavaScript thread than the one in which the handle was created.

Trait Implementations

impl<T> Debug for Root<T>

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

Formats the value using the given formatter.

impl<T> Drop for Root<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Object> Finalize for Root<T>

fn finalize<'a, C: Context<'a>>(self, cx: &mut C)

impl<'cx, O> TryFromJs<'cx> for Root<O>

where O: Object,

type Error = TypeExpected<O>

fn try_from_js( cx: &mut Cx<'cx>, v: Handle<'cx, JsValue>, ) -> NeonResult<Result<Self, Self::Error>>

Extract this Rust type from a JavaScript value

fn from_js(cx: &mut Cx<'cx>, v: Handle<'cx, JsValue>) -> NeonResult<Self>

Same as TryFromJs, but all errors are converted to JavaScript exceptions

impl<'cx, O> TryIntoJs<'cx> for Root<O>

where O: Object,

type Value = O

The type of JavaScript value that will be created

fn try_into_js(self, cx: &mut Cx<'cx>) -> JsResult<'cx, Self::Value>

Convert self into a JavaScript value

impl<T> Send for Root<T>

impl<T> Sync for Root<T>