Skip to main content

Visit Mozilla.org

JSAPI Reference

From MDC

The JSAPI is the C API for the SpiderMonkey JavaScript engine. To learn how to use the JSAPI, see Embedding SpiderMonkey and the JSAPI Phrasebook.

Contents

Alphabetical List

[edit] Runtimes and contexts

Locale callbacks:

Locale callback types:

[edit] Scripts

Just running some JavaScript code is straightforward:

You can instead compile JavaScript code into a JSScript which you can then execute multiple times.

You can also compile JavaScript code into a function:

[edit] Error handling

The following functions allow C/C++ functions to throw and catch JavaScript exceptions:

These functions translate errors into exceptions and vice versa:

[edit] Values and types

jsval constants:

Function and macros for checking the type of a jsval:

An enumeration of all the JavaScript types:

High-level type-conversion routines for packing and unpacking function arguments.

The following functions convert JS values to various types. They can be safely applied to jsvals of any type. They may return new objects. For example, JS_ValueToObject(cx, s) where s is a string creates a new String wrapper object. These functions may call JavaScript methods. For example, JS_ValueToString(cx, obj) may call obj.toString().

Fast, unchecked type-casting macros. These macros must not be applied to values that are not known to be the right type. Like C casts, they may cause crashes if applied to incorrect values. They never create new objects or call into JavaScript code.

An enumeration of JavaScript language versions:

And:

[edit] Memory management

These functions act like the Standard C malloc family of functions, except that errors are reported using the SpiderMonkey error APIs rather than errno:

JavaScript objects, strings, and floating-point numbers are garbage collected. These functions provide access to the garbage collector:

The rest of these APIs help protect objects from being destroyed by the garbage collector before the application is done using them.

If a variable is a root, then anything it points to will not be freed by the garbage collector. Failure to root objects is a very common cause of mysterious crashes.

Local root scopes are another way of protecting objects from the garbage collector.

New in SpiderMonkey 1.8 (not yet released) If an object contains references to other GC things that are not stored in SpiderMonkey data structures ("slots"), it must implement the JSTraceOp hook to enable the garbage collector to traverse those references. Otherwise the garbage collector will not find all reachable objects and may collect objects that are still reachable, leading to a crash. (In SpiderMonkey 1.7 and earlier, the JSMarkOp hook is used instead. This will be deprecated when SpiderMonkey 1.8 is released.)

The tracing APIs are used by the garbage collector and JSTraceOp hooks. JSAPI applications may also use them to examine the object graph. (For example, these APIs support very smooth integration between the JS garbage collector and other garbage collectors.)

Miscellaneous GC APIs:

[edit] Numbers

[edit] Strings

Interning strings tells the SpiderMonkey engine to reuse existing string objects when possible.

The character data for external strings is stored in memory provided by the application. Applications can use this to avoid copying data back and forth between SpiderMonkey's heap and application memory.

[edit] Objects

[edit] Properties

A SpiderMonkey extension allows a native function to return an lvalue—that is, a reference to a property of an object:

A jsid is kind of like a jsval, only different. A handful of APIs use jsids instead of jsvals for property names: JS_CheckAccess, JS_Enumerate, JS_GetMethodById, and JS_NextProperty.

[edit] Classes

These API features are used to define custom classes—object types that are implemented in C/C++ code but accessible from JavaScript.

Adding native properties and methods to classes:

JSFastNative methods use these macros:

The behavior of a JSClass and its instances can be customized in many ways using callback functions.

JSClass method types:

JSExtendedClass method types:

JSObjectOps method types:

JSXMLObjectOps method types:

These stub functions can be used when creating a custom JSClass:

The behavior of a JSClass can be customized using these flags:

[edit] Arrays

[edit] Functions

Calling a function or a method of an object:

Function accessors:

Creating functions:

[edit] RegExps

[edit] Security

[edit] Threading

The following functions support the SpiderMonkey threading model. They are only available in JS_THREADSAFE builds.

The following functions exist in all builds, but in non-JS_THREADSAFE builds, they do nothing:

[edit] Time

[edit] Callback Types

Native function types:

Other callback types:

See also Classes, above.

[edit] Macros

[edit] Preprocessor conditionals

[edit] C++ features

Retrieved from "http://developer.mozilla.org/en/docs/JSAPI_Reference"