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§
- The result of a call to
Handle::downcast()
.