Obsolete since JavaScript 1.8.5
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

This article covers features introduced in SpiderMonkey 1.8

JSFastNative is the type of fast native functions in the JSAPI. APIs such as JS_InitClass and JS_DefineFunctions can create custom methods that are implemented as C/C++ functions of this type, instead of JSNative.

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

Added in SpiderMonkey 1.8.1 JSFastNative has been renamed to JSNative.

Syntax

typedef JSBool
(*JSFastNative)(JSContext *cx, unsigned int argc, jsval *vp);
Name Type Description
cx JSContext * The context in which the fast native 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 int 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 jsval * The arguments, including the this argument, the return-value slot, and the callee Function object are accessible through this pointer using macros described below.

Description

The callback should use the following macros to access the fields of vp:

Macro name Description
JS_CALLEE(cx, vp) Returns the Function object that was called, as a jsval.

Native methods must not call JS_CALLEE after calling JS_SET_RVAL. (The return value and the callee are stored in the same stack slot.)
JS_THIS(cx, vp) Returns the this argument as a jsval, or JSVAL_NULL on error.

Native methods must not call JS_THIS after calling JS_SET_RVAL. (JS_THIS may call JS_CALLEE.)
JS_THIS_OBJECT(cx, vp) Returns the this argument as a JSObject *, or NULL on error.

Native methods must not call JS_THIS_OBJECT after calling JS_SET_RVAL. (JS_THIS_OBJECT may call JS_CALLEE.)
JS_ARGV(cx, vp) Returns the argv pointer. This points to element 0 of an array of argc jsvals, the arguments supplied by the caller.
JS_RVAL(cx, vp) Returns the jsval that is currently in the return-value slot.
JS_SET_RVAL(cx, vp, value) Sets the return value of the native function. It is safe to call this multiple times within a single call to a JSFastNative. If the JSFastNative returns JS_TRUE, the last value passed to this macro will be returned to the caller.

On success, the callback must call JS_SET_RVAL (at least once) and return JS_TRUE. On error or exception, it must return JS_FALSE.

To create a JSFunctionSpec that points to a JSFastNative, use JS_FN.

When a JSFastNative is called, no JSStackFrame is generated. This is what makes a fast native fast. However, it causes the function not to appear on the stack in JavaScript debuggers. It also means that applications that use SpiderMonkey's security features, particularly those 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.

See Also