JS::Handle

This article covers features introduced in SpiderMonkey 17

Reference to a T that has been rooted elsewhere. This is most useful as a parameter type, which guarantees that the T value is properly rooted.

Syntax

bool
someFunction(JSContext *cx, JS::Handle<T> var) {
...
}

Methods

Here, ptr represents the private member of JS::Handle<T>, typed with T.

Method Description
const T *address() const Returns a pointer to ptr.
const T &get() const Returns ptr.
operator const T&() const
T operator->() const
bool operator!=(const T &other) const Compares ptr and other.
bool operator==(const T &other) const

Description

JS::Handle<T> is a const reference to a JS::Rooted<T>. Functions which take GC things or values as arguments and need to root those arguments should generally use handles for those arguments and avoid any explicit rooting. This has two benefits. First, when several such functions call each other then redundant rooting of multiple copies of the GC thing can be avoided. Second, if the caller does not pass a rooted value a compile error will be generated, which is quicker and easier to fix than when relying on a separate rooting analysis.

If you want to add additional methods to JS::Handle for a specific specialization, define a js::HandleBase<T> specialization containing them.

There are typedefs available for the main types:

namespace JS {
typedef Handle<JSFunction*> HandleFunction;
typedef Handle<jsid>        HandleId;
typedef Handle<JSObject*>   HandleObject;
typedef Handle<JSScript*>   HandleScript;
typedef Handle<JSString*>   HandleString;
typedef Handle<JS::Symbol*> HandleSymbol; // Added in SpiderMonkey 38
typedef Handle<Value>       HandleValue;
}

See Also

Document Tags and Contributors

Tags: 
 Contributors to this page: FlyingJester, kscarfone, arai
 Last updated by: FlyingJester,