JSNative

  • Revision slug: SpiderMonkey/JSAPI_Reference/JSNative
  • Revision title: JSNative
  • Revision id: 105115
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 526 words added, 265 words removed

Revision Content

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, uintN argc, jsval *vp);
Name Type Description
cx JSContext * The context in which the native function 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, 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.

On success, the callback must call JS_SET_RVAL (at least once) and return JS_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 JS_FALSE.

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.

When a JSNative is invoked by SpiderMonkey, the following locations are all 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].

JSNatives are free to assign to the elements of JS_ARGV(cx, vp). Calling JS_ConvertArguments does this, for example.

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

Revision Source

<p><strong><code>JSNative</code></strong> is the type of many JSAPI callbacks. In particular, APIs such as <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_InitClass" title="en/SpiderMonkey/JSAPI_Reference/JS_InitClass">JS_InitClass</a></code> and <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineFunctions" title="en/SpiderMonkey/JSAPI_Reference/JS_DefineFunctions">JS_DefineFunctions</a></code> create custom methods on JavaScript objects that are implemented as <code>JSNative</code> callbacks provided by the application, written in C/C++ code.</p>
<p>The term "native" here refers to C/C++ code as opposed to JavaScript code.</p>
<h2 name="Syntax">Syntax</h2>
<pre class="eval">typedef <a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> (*<strong>JSNative</strong>)(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> argc, <a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="en/jsval">jsval</a> *vp);
</pre>
<table class="fullwidth-table"> <tbody> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> <tr> <td><code>cx</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *</code></td> <td>The context in which the native function is being called. {{ Jsapi_provides_request() }}</td> </tr> <tr> <td><code>argc</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a></code></td> <td>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 <code><a href="/En/SpiderMonkey/JSAPI_Reference/JSFunctionSpec" title="en/JSFunctionSpec">JSFunctionSpec</a></code>).</td> </tr> <tr> <td><code>vp</code></td> <td><code><a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="en/jsval">jsval</a> *</code></td> <td>The arguments, the <code>this</code> argument, the return-value slot, and the callee <code>Function</code> object are accessible through this pointer using macros described below.</td> </tr> </tbody>
</table>
<h2 name="Description">Description</h2>
<p><code>JSNative</code> is the type of native implementations of JavaScript functions.</p>
<p>On success, the callback must call <code>JS_SET_RVAL</code> (at least once) and return <code>JS_TRUE</code>. Otherwise it must either report an error (using e.g. <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_ReportError" title="en/SpiderMonkey/JSAPI_Reference/JS_ReportError">JS_ReportError</a></code> or <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_ReportOutOfMemory" title="en/SpiderMonkey/JSAPI_Reference/JS_ReportOutOfMemory">JS_ReportOutOfMemory</a></code>) or raise an exception (using <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetPendingException" title="en/SpiderMonkey/JSAPI_Reference/JS_SetPendingException">JS_SetPendingException</a></code>), and the callback must return <code>JS_FALSE</code>.</p>
<p>The callback should use the following macros to access the fields of <code>vp</code>:</p>
<table class="fullwidth-table"> <tbody> <tr> <th>Macro name</th> <th>Description</th> </tr> <tr> <td><code><strong>JS_CALLEE</strong>(cx, vp)</code></td> <td>Returns the <code>Function</code> object that was called, as a <code>jsval</code>. <p>Native methods must not call <code>JS_CALLEE</code> after calling <code>JS_SET_RVAL</code>. (The return value and the callee are stored in the same stack slot.)</p> </td> </tr> <tr> <td><code><strong>JS_THIS</strong>(cx, vp)</code></td> <td>Returns the <code>this</code> argument as a <code>jsval</code>, or <code>JSVAL_NULL</code> on error. <p>Native methods must not call <code>JS_THIS</code> after calling <code>JS_SET_RVAL</code>. (<code>JS_THIS</code> may call <code>JS_CALLEE</code>.)</p> </td> </tr> <tr> <td><code><strong>JS_THIS_OBJECT</strong>(cx, vp)</code></td> <td>Returns the <code>this</code> argument as a <code>JSObject *</code>, or <code>NULL</code> on error. <p>Native methods must not call <code>JS_THIS_OBJECT</code> after calling <code>JS_SET_RVAL</code>. (<code>JS_THIS_OBJECT</code> may call <code>JS_CALLEE</code>.)</p> </td> </tr> <tr> <td><code><strong>JS_ARGV</strong>(cx, vp)</code></td> <td>Returns the <code>argv</code> pointer. This points to element 0 of an array of <code>argc</code> <code>jsval</code>s, the arguments supplied by the caller.</td> </tr> <tr> <td><code><strong>JS_RVAL</strong>(cx, vp)</code></td> <td>Returns the <code>jsval</code> that is currently in the return-value slot.</td> </tr> <tr> <td><code><strong>JS_SET_RVAL</strong>(cx, vp, value)</code></td> <td>Sets the return value of the native function. It is safe to call this multiple times within a single call to a <code>JSFastNative</code>. If the <code>JSFastNative</code> returns <code>JS_TRUE</code>, the last <code>value</code> passed to this macro will be returned to the caller.</td> </tr> </tbody>
</table>
<p>When a <code>JSNative</code> is invoked by SpiderMonkey, the following locations are all GC roots:</p>
<ul> <li>The location where <code>JS_CALLEE(cx, vp)</code> is stored, until the first call to <code>JS_SET_RVAL</code>.</li> <li>The location where the return value is stored, after a call to <code>JS_SET_RVAL</code>. This is currently the same location as the callee.</li> <li>The location where <code>JS_THIS(cx, vp)</code> is stored.</li> <li>The locations where the arguments are stored, namely <code>JS_ARGV(cx, vp)[0]</code> through <code>JS_ARGV(cx, vp)[argc - 1]</code>.</li>
</ul>
<p><code>JSNative</code>s are free to assign to the elements of <code>JS_ARGV(cx, vp)</code>. Calling <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_ConvertArguments" title="en/SpiderMonkey/JSAPI_Reference/JS_ConvertArguments">JS_ConvertArguments</a></code> does this, for example.</p>
<p>{{ Warning("When a <code>JSNative</code> is called, no <a href='\"en/SpiderMonkey/JSAPI_Reference/JSStackFrame\"'><code>JSStackFrame</code></a> is generated. This causes the function not to appear on the stack in JavaScript debuggers. It also means that applications that implement <code><a href='\"en/SpiderMonkey/JSAPI_Reference/JSCheckAccessOp\"'>JSCheckAccessOp</a></code> or <code><a href='\"en/SpiderMonkey/JSAPI_Reference/JSCheckAccessIdOp\"'>JSCheckAccessIdOp</a></code> in terms of APIs such as <code><a href='\"en/SpiderMonkey/JSAPI_Reference/JS_FrameIterator\"'>JS_FrameIterator</a></code> and <code><a href='\"en/SpiderMonkey/JSAPI_Reference/JS_StackFramePrincipals\"'>JS_StackFramePrincipals</a></code>, must take extra care, as the native function\'s principals will be missing from the stack.") }}</p>
Revert to this revision