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.

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

• MXR ID Search for JS::Handle
• MXR ID Search for JS::HandleFunction
• MXR ID Search for JS::HandleId
• MXR ID Search for JS::HandleObject
• MXR ID Search for JS::HandleScript
• MXR ID Search for JS::HandleString
• MXR ID Search for JS::HandleSymbol
• MXR ID Search for JS::HandleValue
• JS::Rooted
• JS::MutableHandle
• GC Rooting Guide
• bug 714647
• bug 761391 - added JS::HandleScript
• bug 645416 - added JS::HandleSymbol