Module neon::handle

source ·
Expand description

References to garbage-collected JavaScript values.

A handle is a safe reference to a JavaScript value that is owned and managed by the JavaScript engine’s memory management system (the garbage collector).

Neon APIs that accept and return JavaScript values never use raw pointer types (*T) or reference types (&T). Instead they use the special Neon type Handle, which encapsulates a JavaScript Value and ensures that Rust only maintains access to the value while it is guaranteed to be valid.

§Working with Handles

The Handle<T> type automatically dereferences to T (via the standard Deref trait), so you can call T’s methods on a value of type Handle<T>. For example, we can call JsNumber::value() on a Handle<JsNumber>:

let n: Handle<JsNumber> = cx.argument(0)?;
let v = n.value(&mut cx); // JsNumber::value()

§Example

This Neon function takes an object as its argument, extracts two properties, width and height, and multiplies them together as numbers. Each JavaScript value in the calculation is stored locally in a Handle.

fn area(mut cx: FunctionContext) -> JsResult<JsNumber> {
    let rect: Handle<JsObject> = cx.argument(0)?;

    let width: Handle<JsNumber> = rect.get(&mut cx, "width")?;
    let w: f64 = width.value(&mut cx);

    let height: Handle<JsNumber> = rect.get(&mut cx, "height")?;
    let h: f64 = height.value(&mut cx);

    Ok(cx.number(w * h))
}

Structs§

  • An error representing a failed downcast.
  • A handle to a JavaScript value that is owned by the JavaScript engine.
  • A thread-safe handle that holds a reference to a JavaScript object and prevents it from being garbage collected.

Type Aliases§