Compare Revisions

JSAPI User Guide

Revision 311151:

Revision 311151 by GeertVL on

Revision 325659:

Revision 325659 by Jorend on

Title:
JSAPI User Guide
JSAPI User Guide
Slug:
SpiderMonkey/JSAPI_User_Guide
SpiderMonkey/JSAPI_User_Guide
Tags:
"SpiderMonkey","NeedsTechnicalReview","JavaScript"
"SpiderMonkey","NeedsTechnicalReview","JavaScript"
Content:

Revision 311151
Revision 325659
n8      This document explains how to embed <a href="/en/SpiderMonkn8      This document explains how to embed <a href="/en/SpiderMonk
>ey" title="en/SpiderMonkey">SpiderMonkey</a>, the Mozilla JavaScr>ey" title="en/SpiderMonkey">SpiderMonkey</a>, the Mozilla JavaScr
>ipt engine, in your C/C++ program.>ipt engine, in your C++ program.
9    </p>
10    <p>9    </p>
10    <p>
11      JavaScript is widely used for client-side scripts that run 11      JavaScript is widely used for client-side scripts that run 
>in the browser. But Mozilla's JavaScript engine is a library that>in the browser. But Mozilla's JavaScript engine is a library that
> can be linked into any C/C++ program, not just a browser. Many a> can be linked into any C++ program, not just a browser. Many app
>pplications can benefit from scripting. These programs can execut>lications can benefit from scripting. These programs can execute 
>e JavaScript code from C using the SpiderMonkey API.>JavaScript code from C++ using the SpiderMonkey API.
n35      Your application can use SpiderMonkey like any other C/C++ n35      Your application can use SpiderMonkey like any other C++ li
>library. To build SpiderMonkey from source, see <a href="/En/Spid>brary. To build SpiderMonkey from source, see <a href="/En/Spider
>erMonkey/Build_Documentation" title="en/SpiderMonkey_Build_Docume>Monkey/Build_Documentation" title="en/SpiderMonkey_Build_Document
>ntation">SpiderMonkey Build Documentation</a>. You can build Spid>ation">SpiderMonkey Build Documentation</a>. You can build Spider
>erMonkey as a static library or as a shared library.>Monkey as a static library or as a shared library.
n41      C/C++ code accesses SpiderMonkey via the JSAPI, by includinn41      C++ code accesses SpiderMonkey via the JSAPI, by including 
>g the header <code>"jsapi.h"</code>. The JSAPI provides functions>the header <code>"jsapi.h"</code>. The JSAPI provides functions f
> for setting up the JavaScript runtime, compiling and executing s>or setting up the JavaScript runtime, compiling and executing scr
>cripts, creating and examining JavaScript data structures, handli>ipts, creating and examining JavaScript data structures, handling
>ng errors, enabling security checks, and debugging scripts.> errors, enabling security checks, and debugging scripts.
nn111 
nn113 
nn116 
n116     fprintf(stderr, "%s:%u:%s\n", report-&gt;filename ? report-&n119     fprintf(stderr, "%s:%u:%s\n",
>gt;filename : "", (unsigned int) report-&gt;lineno, message); 
117 120             report-&gt;filename ? report-&gt;filename : "",
121             (unsigned int) report-&gt;lineno,
122             message);
nn130 
nn135 
nn143 
nn148 
n165      Native functions are implemented in C/C++ but can be calledn174      Native functions are implemented in C++ but can be called f
> from JavaScript just like any other function. The native functio>rom JavaScript just like any other function. The native function'
>n's signature must match <a class="internal" href="/en/SpiderMonk>s signature must match <a class="internal" href="/en/SpiderMonkey
>ey/JSAPI_Reference/JSNative" title="En/JSNative"><code>JSNative</>/JSAPI_Reference/JSNative" title="En/JSNative"><code>JSNative</co
>code></a>.>de></a>.
n228      The JavaScript arguments to the function are given in <coden237      The JavaScript arguments to the function are given in <code
>>argc</code> and <code>vp</code>. <code>argc</code> tells how man>>argc</code> and <code>vp</code>. <code>argc</code> tells how man
>y actual arguments the caller passed, and <code>JS_ARGV(cx, vp)</>y actual arguments the caller passed, and <code>JS_ARGV(cx, vp)</
>code> returns an array of those arguments. The arguments do not h>code> returns an array of those arguments. The arguments do not h
>ave native C/C++ types like <code>int</code> and <code>float</cod>ave native C++ types like <code>int</code> and <code>float</code>
>e>; rather, they are <a class="internal" href="/En/SpiderMonkey/J>; rather, they are <a class="internal" href="/En/SpiderMonkey/JSA
>SAPI_Reference/Jsval" title="en/jsval"><code>jsval</code></a>s, J>PI_Reference/Jsval" title="en/jsval"><code>jsval</code></a>s, Jav
>avaScript values. The native function uses <a class="internal" hr>aScript values. The native function uses <a class="internal" href
>ef="/en/SpiderMonkey/JSAPI_Reference/JS_ConvertArguments" title=">="/en/SpiderMonkey/JSAPI_Reference/JS_ConvertArguments" title="en
>en/JS_ConvertArguments"><code>JS_ConvertArguments</code></a> to c>/JS_ConvertArguments"><code>JS_ConvertArguments</code></a> to con
>onvert the arguments to C/C++ types and store them in local varia>vert the arguments to C++ types and store them in local variables
>bles. The native function uses <code>JS_SET_RVAL(cx, vp, val)</co>. The native function uses <code>JS_SET_RVAL(cx, vp, val)</code> 
>de> to store its JavaScript return value.>to store its JavaScript return value.
n278        <strong>Warning:</strong> Like C/C++ pointers, and unliken287        <strong>Warning:</strong> Like C++ pointers, and unlike J
> JavaScript <code>var</code>s, a <code>jsval</code> is <strong>no>avaScript <code>var</code>s, a <code>jsval</code> is <strong>not<
>t</strong> automatically initialized to a safe value, and <strong>/strong> automatically initialized to a safe value, and <strong>c
>>can</strong> become a dangling pointer!>an</strong> become a dangling pointer!
n281        A dangling pointer is a pointer that used to point to a vn290        A dangling pointer is a pointer that used to point to a v
>alid object, but no longer does because the object no longer exis>alid object, but no longer does because the object no longer exis
>ts. Using a dangling pointer can crash a C/C++ program (or worse)>ts. Using a dangling pointer can crash a C++ program (or worse). 
>. In the case of <code>jsval</code>, the JavaScript garbage colle>In the case of <code>jsval</code>, the JavaScript garbage collect
>ctor recycles objects, strings, and numbers that don't appear to >or recycles objects, strings, and numbers that don't appear to be
>be in use, and a <code>jsval</code> by itself does not protect it> in use, and a <code>jsval</code> by itself does not protect its 
>s referent from the garbage collector. See <em>Garbage collection>referent from the garbage collector. See <em>Garbage collection</
></em> below for crucial information on how to use <code>jsval</co>em> below for crucial information on how to use <code>jsval</code
>de>s safely.>>s safely.
t400      Once the C/C++ function returns JS_FALSE, the JavaScript ent409      Once the C++ function returns JS_FALSE, the JavaScript engi
>gine starts unwinding the JavaScript stack, looking for a <code>c>ne starts unwinding the JavaScript stack, looking for a <code>cat
>atch</code> or <code>finally</code> block to execute. But SpiderM>ch</code> or <code>finally</code> block to execute. But SpiderMon
>onkey's stack unwinding never removes application's C/C++ functio>key's stack unwinding never removes application's C++ functions f
>ns from the stack. Instead, SpiderMonkey simply returns <code>JS_>rom the stack. Instead, SpiderMonkey simply returns <code>JS_FALS
>FALSE</code> or <code>NULL</code> to the application, which can t>E</code> or <code>NULL</code> to the application, which can then 
>hen handle the error as it chooses—or just return <code>JS_FALSE<>handle the error as it chooses—or just return <code>JS_FALSE</cod
>/code> to let it propagate further up the stack.>e> to let it propagate further up the stack.

Back to History