JSNative

JSNative is the type of many JSAPI callbacks. In particular, APIs such as JS_InitClass and JS_DefineFunctions create custom methods on JavaScript objects that are implemented as JSNative callbacks provided by the application, written in C/C++ code.

The term "native" here refers to C/C++ code as opposed to JavaScript code.

Syntax

typedef JSBool (*JSNative)(JSContext *cx, unsigned argc, JS::Value *vp);
Name Type Description
cx JSContext * The context in which the native function is being called. Provides request. In JS_THREADSAFE builds, the JavaScript engine calls this callback only from within an active request on cx. The callback does not need to call JS_BeginRequest()).
argc unsigned 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 JSFunctionSpec).
vp JS::Value * The arguments, the this argument, the return-value slot, and the callee Function object are accessible through this pointer using macros described below.

Description

JSNative is the type of native implementations of JavaScript functions.  Full documentation of how to define a JSNative (or a JSFastNative, the equivalent typedef which preceded it) is available in the API header "js/CallArgs.h" Added in SpiderMonkey 24.  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 Added in SpiderMonkey 17. (This structure is now provided in "js/CallArgs.h" Added in SpiderMonkey 24 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_ReportError or JS_ReportOutOfMemory) or raise an exception (using JS_SetPendingException), and the callback must return false.

Returning 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 JS_SET_RVAL.
  • 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)[0] through 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.)

When a JSNative is called, no JSStackFrame is generated. This causes the function not to appear on the stack in JavaScript debuggers. It also means that applications that implement JSCheckAccessOp or JSCheckAccessIdOp in terms of APIs such as JS_FrameIterator and JS_StackFramePrincipals, must take extra care, as the native function's principals will be missing from the stack.

 

Document Tags and Contributors

Contributors to this page: lordblackfox, Nickolay, Jorend, Waldo
Last updated by: lordblackfox,