JS::Rooted

This article covers features introduced in SpiderMonkey 17

Local variable of type T whose value is always rooted.

Syntax

JS::Rooted<T> var(cx);
JS::Rooted<T> var(cx, initial);
JS::Rooted<T> var(rt);
JS::Rooted<T> var(rt, initial);
Name Type Description
cx JSContext * The context in which to add the root. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
rt JSRuntime * The runtime in which to add the root.
initial T An initial value for the rooted variable.

Methods

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

Method Description
T &get() Returns ptr.
const T &get() const
operator const T&() const
T operator->() const
T *address() Returns a pointer to ptr.
const T *address() const
T &operator=(T value) Sets the value of ptr to value.
T &operator=(const Rooted &value)
void set(T value)
bool operator!=(const T &other) const Compares ptr and other.
bool operator==(const T &other) const

Description

JS::Rooted<T> declares a local variable of type T whose value is always rooted. This is typically used for local variables, or for non-rooted values being passed to a function that requires a handle, e.g. Foo(JS::Rooted<T>(cx, x)).

JS::Rooted<T> may be automatically coerced to a JS::Handle&lt;T&gt;. JS::Rooted<T> should be used whenever a local variable's value may be held live across a call which can trigger a GC.

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

There are typedefs available for the main types:

namespace JS {
typedef Rooted<JSObject*>       RootedObject;
typedef Rooted<JSFunction*>     RootedFunction;
typedef Rooted<JSScript*>       RootedScript;
typedef Rooted<JSString*>       RootedString;
typedef Rooted<JS::Symbol*>     RootedSymbol; // Added in SpiderMonkey 38
typedef Rooted<jsid>            RootedId;
typedef Rooted<JS::Value>       RootedValue;
}

See Also