JSNative is the type of many JSAPI callbacks. In particular, APIs such as
JSNative callbacks provided by the application, written in C/C++ code.
||The context in which the native function is being called. Provides request. In
||The number of arguments supplied to the function by the caller (as opposed to, say, the number of arguments the function is specified to take in its
||The arguments, the
JSNative (or a
JSFastNative, the equivalent
typedef which preceded it) is available in the API header
"js/CallArgs.h" . This header is new, but the semantics it describes are applicable to all recent SpiderMonkey releases. The preferred way to implement a function is to use the
JS::CallArgs structure defined there; the macros providing equivalent functionality are deprecated.
The behavior of a
JSNative is implemented using a
JS::CallArgs structure . (This structure is now provided in
"js/CallArgs.h" as well as through
"jsapi.h".) This structure encapsulates access to the callee function,
this, the function call's arguments, and the eventual return value.
On success, the callback must set
JS::CallArgs::rval() or call
JS_SET_RVAL (at least once) and return
true. Otherwise it must either report an error (using e.g.
JS_ReportOutOfMemory) or raise an exception (using
JS_SetPendingException), and the callback must return
false without reporting an error or raising an exception exits the script.
Historically, all the following locations accessible in a
JSNative invoked by SpiderMonkey were GC roots:
- The location where
JS_CALLEE(cx, vp)is stored, until the first call to
- The location where the return value is stored, after a call to
JS_SET_RVAL. This is currently the same location as the callee.
- The location where
JS_THIS(cx, vp)is stored.
- The locations where the arguments are stored, namely
JS_ARGV(cx, vp)[argc - 1].
New code should not treat any of these locations as roots. Instead,
JS::Rooted<Value> should be used to provide extra individual GC roots as needed. (Note that it is illegal to use
JS::Rooted in heap structures or in arrays: it is only valid when used directly on the stack.)
JSNative is called, no
JSCheckAccessIdOp in terms of APIs such as
JS_StackFramePrincipals, must take extra care, as the native function's principals will be missing from the stack.