mozilla

JSFastNative

There was a scripting error on this page. While it is being addressed by site editors, you can view partial content below.

{{ template{path: "template:deprecated"} }}

{{ jsapi_minversion_header("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.

{{ jsapi_minversion_inline("1.8.1") }} JSFastNative has been renamed to JSNative.

Syntax

typedef JSBool (*JSFastNative)(JSContext *cx, uintN argc, jsval *vp);
Name Type Description
cx JSContext * The context in which the fast native is being called. {{ Jsapi_provides_request() }}
argc uintN 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.

{{ Warning("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.") }}

{{ LXRSearch("ident", "i", "JSFastNative") }}

Document Tags and Contributors

Contributors to this page: Jorend
Last updated by: Jorend,