PageRenderTime 73ms CodeModel.GetById 28ms app.highlight 33ms RepoModel.GetById 1ms app.codeStats 1ms

/js/lib/Socket.IO-node/support/expresso/deps/jscoverage/js/jsapi.h

http://github.com/onedayitwillmake/RealtimeMultiplayerNodeJs
C++ Header | 1674 lines | 791 code | 260 blank | 623 comment | 17 complexity | cf77e201624c20fcd17a922d9ee7611b MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2 * vim: set ts=8 sw=4 et tw=78:
   3 *
   4 * ***** BEGIN LICENSE BLOCK *****
   5 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version
   8 * 1.1 (the "License"); you may not use this file except in compliance with
   9 * the License. You may obtain a copy of the License at
  10 * http://www.mozilla.org/MPL/
  11 *
  12 * Software distributed under the License is distributed on an "AS IS" basis,
  13 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14 * for the specific language governing rights and limitations under the
  15 * License.
  16 *
  17 * The Original Code is Mozilla Communicator client code, released
  18 * March 31, 1998.
  19 *
  20 * The Initial Developer of the Original Code is
  21 * Netscape Communications Corporation.
  22 * Portions created by the Initial Developer are Copyright (C) 1998
  23 * the Initial Developer. All Rights Reserved.
  24 *
  25 * Contributor(s):
  26 *
  27 * Alternatively, the contents of this file may be used under the terms of
  28 * either of the GNU General Public License Version 2 or later (the "GPL"),
  29 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30 * in which case the provisions of the GPL or the LGPL are applicable instead
  31 * of those above. If you wish to allow use of your version of this file only
  32 * under the terms of either the GPL or the LGPL, and not to allow others to
  33 * use your version of this file under the terms of the MPL, indicate your
  34 * decision by deleting the provisions above and replace them with the notice
  35 * and other provisions required by the GPL or the LGPL. If you do not delete
  36 * the provisions above, a recipient may use your version of this file under
  37 * the terms of any one of the MPL, the GPL or the LGPL.
  38 *
  39 * ***** END LICENSE BLOCK ***** */
  40
  41#ifndef jsapi_h___
  42#define jsapi_h___
  43/*
  44 * JavaScript API.
  45 */
  46#include <stddef.h>
  47#include <stdio.h>
  48#include "js-config.h"
  49#include "jspubtd.h"
  50#include "jsutil.h"
  51
  52JS_BEGIN_EXTERN_C
  53
  54/*
  55 * Type tags stored in the low bits of a jsval.
  56 */
  57#define JSVAL_OBJECT            0x0     /* untagged reference to object */
  58#define JSVAL_INT               0x1     /* tagged 31-bit integer value */
  59#define JSVAL_DOUBLE            0x2     /* tagged reference to double */
  60#define JSVAL_STRING            0x4     /* tagged reference to string */
  61#define JSVAL_BOOLEAN           0x6     /* tagged boolean value */
  62
  63/* Type tag bitfield length and derived macros. */
  64#define JSVAL_TAGBITS           3
  65#define JSVAL_TAGMASK           JS_BITMASK(JSVAL_TAGBITS)
  66#define JSVAL_TAG(v)            ((v) & JSVAL_TAGMASK)
  67#define JSVAL_SETTAG(v,t)       ((v) | (t))
  68#define JSVAL_CLRTAG(v)         ((v) & ~(jsval)JSVAL_TAGMASK)
  69#define JSVAL_ALIGN             JS_BIT(JSVAL_TAGBITS)
  70
  71/* Predicates for type testing. */
  72#define JSVAL_IS_OBJECT(v)      (JSVAL_TAG(v) == JSVAL_OBJECT)
  73#define JSVAL_IS_NUMBER(v)      (JSVAL_IS_INT(v) || JSVAL_IS_DOUBLE(v))
  74#define JSVAL_IS_INT(v)         ((v) & JSVAL_INT)
  75#define JSVAL_IS_DOUBLE(v)      (JSVAL_TAG(v) == JSVAL_DOUBLE)
  76#define JSVAL_IS_STRING(v)      (JSVAL_TAG(v) == JSVAL_STRING)
  77#define JSVAL_IS_BOOLEAN(v)     (((v) & ~((jsval)1 << JSVAL_TAGBITS)) ==      \
  78                                 JSVAL_BOOLEAN)
  79#define JSVAL_IS_NULL(v)        ((v) == JSVAL_NULL)
  80#define JSVAL_IS_VOID(v)        ((v) == JSVAL_VOID)
  81#define JSVAL_IS_PRIMITIVE(v)   (!JSVAL_IS_OBJECT(v) || JSVAL_IS_NULL(v))
  82
  83/* Objects, strings, and doubles are GC'ed. */
  84#define JSVAL_IS_GCTHING(v)     (!((v) & JSVAL_INT) &&                        \
  85                                 JSVAL_TAG(v) != JSVAL_BOOLEAN)
  86#define JSVAL_TO_GCTHING(v)     ((void *)JSVAL_CLRTAG(v))
  87#define JSVAL_TO_OBJECT(v)      ((JSObject *)JSVAL_TO_GCTHING(v))
  88#define JSVAL_TO_DOUBLE(v)      ((jsdouble *)JSVAL_TO_GCTHING(v))
  89#define JSVAL_TO_STRING(v)      ((JSString *)JSVAL_TO_GCTHING(v))
  90#define OBJECT_TO_JSVAL(obj)    ((jsval)(obj))
  91#define DOUBLE_TO_JSVAL(dp)     JSVAL_SETTAG((jsval)(dp), JSVAL_DOUBLE)
  92#define STRING_TO_JSVAL(str)    JSVAL_SETTAG((jsval)(str), JSVAL_STRING)
  93
  94/* Lock and unlock the GC thing held by a jsval. */
  95#define JSVAL_LOCK(cx,v)        (JSVAL_IS_GCTHING(v)                          \
  96                                 ? JS_LockGCThing(cx, JSVAL_TO_GCTHING(v))    \
  97                                 : JS_TRUE)
  98#define JSVAL_UNLOCK(cx,v)      (JSVAL_IS_GCTHING(v)                          \
  99                                 ? JS_UnlockGCThing(cx, JSVAL_TO_GCTHING(v))  \
 100                                 : JS_TRUE)
 101
 102/* Domain limits for the jsval int type. */
 103#define JSVAL_INT_BITS          31
 104#define JSVAL_INT_POW2(n)       ((jsval)1 << (n))
 105#define JSVAL_INT_MIN           (-JSVAL_INT_POW2(30))
 106#define JSVAL_INT_MAX           (JSVAL_INT_POW2(30) - 1)
 107#define INT_FITS_IN_JSVAL(i)    ((jsuint)(i) - (jsuint)JSVAL_INT_MIN <=      \
 108                                 (jsuint)(JSVAL_INT_MAX - JSVAL_INT_MIN))
 109#define JSVAL_TO_INT(v)         ((jsint)(v) >> 1)
 110#define INT_TO_JSVAL(i)         (((jsval)(i) << 1) | JSVAL_INT)
 111
 112/* Convert between boolean and jsval. */
 113#define JSVAL_TO_BOOLEAN(v)     ((JSBool)((v) >> JSVAL_TAGBITS))
 114#define BOOLEAN_TO_JSVAL(b)     JSVAL_SETTAG((jsval)(b) << JSVAL_TAGBITS,     \
 115                                             JSVAL_BOOLEAN)
 116
 117/* A private data pointer (2-byte-aligned) can be stored as an int jsval. */
 118#define JSVAL_TO_PRIVATE(v)     ((void *)((v) & ~JSVAL_INT))
 119#define PRIVATE_TO_JSVAL(p)     ((jsval)(p) | JSVAL_INT)
 120
 121/* Property attributes, set in JSPropertySpec and passed to API functions. */
 122#define JSPROP_ENUMERATE        0x01    /* property is visible to for/in loop */
 123#define JSPROP_READONLY         0x02    /* not settable: assignment is no-op */
 124#define JSPROP_PERMANENT        0x04    /* property cannot be deleted */
 125#define JSPROP_GETTER           0x10    /* property holds getter function */
 126#define JSPROP_SETTER           0x20    /* property holds setter function */
 127#define JSPROP_SHARED           0x40    /* don't allocate a value slot for this
 128                                           property; don't copy the property on
 129                                           set of the same-named property in an
 130                                           object that delegates to a prototype
 131                                           containing this property */
 132#define JSPROP_INDEX            0x80    /* name is actually (jsint) index */
 133
 134/* Function flags, set in JSFunctionSpec and passed to JS_NewFunction etc. */
 135#define JSFUN_LAMBDA            0x08    /* expressed, not declared, function */
 136#define JSFUN_GETTER            JSPROP_GETTER
 137#define JSFUN_SETTER            JSPROP_SETTER
 138#define JSFUN_BOUND_METHOD      0x40    /* bind this to fun->object's parent */
 139#define JSFUN_HEAVYWEIGHT       0x80    /* activation requires a Call object */
 140
 141#define JSFUN_DISJOINT_FLAGS(f) ((f) & 0x0f)
 142#define JSFUN_GSFLAGS(f)        ((f) & (JSFUN_GETTER | JSFUN_SETTER))
 143
 144#define JSFUN_GETTER_TEST(f)       ((f) & JSFUN_GETTER)
 145#define JSFUN_SETTER_TEST(f)       ((f) & JSFUN_SETTER)
 146#define JSFUN_BOUND_METHOD_TEST(f) ((f) & JSFUN_BOUND_METHOD)
 147#define JSFUN_HEAVYWEIGHT_TEST(f)  ((f) & JSFUN_HEAVYWEIGHT)
 148
 149#define JSFUN_GSFLAG2ATTR(f)       JSFUN_GSFLAGS(f)
 150
 151#define JSFUN_THISP_FLAGS(f)  (f)
 152#define JSFUN_THISP_TEST(f,t) ((f) & t)
 153
 154#define JSFUN_THISP_STRING    0x0100    /* |this| may be a primitive string */
 155#define JSFUN_THISP_NUMBER    0x0200    /* |this| may be a primitive number */
 156#define JSFUN_THISP_BOOLEAN   0x0400    /* |this| may be a primitive boolean */
 157#define JSFUN_THISP_PRIMITIVE 0x0700    /* |this| may be any primitive value */
 158
 159#define JSFUN_FAST_NATIVE     0x0800    /* JSFastNative needs no JSStackFrame */
 160
 161#define JSFUN_FLAGS_MASK      0x0ff8    /* overlay JSFUN_* attributes --
 162                                           note that bit #15 is used internally
 163                                           to flag interpreted functions */
 164
 165#define JSFUN_STUB_GSOPS      0x1000    /* use JS_PropertyStub getter/setter
 166                                           instead of defaulting to class gsops
 167                                           for property holding function */
 168
 169/*
 170 * Re-use JSFUN_LAMBDA, which applies only to scripted functions, for use in
 171 * JSFunctionSpec arrays that specify generic native prototype methods, i.e.,
 172 * methods of a class prototype that are exposed as static methods taking an
 173 * extra leading argument: the generic |this| parameter.
 174 *
 175 * If you set this flag in a JSFunctionSpec struct's flags initializer, then
 176 * that struct must live at least as long as the native static method object
 177 * created due to this flag by JS_DefineFunctions or JS_InitClass.  Typically
 178 * JSFunctionSpec structs are allocated in static arrays.
 179 */
 180#define JSFUN_GENERIC_NATIVE    JSFUN_LAMBDA
 181
 182/*
 183 * Well-known JS values.  The extern'd variables are initialized when the
 184 * first JSContext is created by JS_NewContext (see below).
 185 */
 186#define JSVAL_VOID              BOOLEAN_TO_JSVAL(2)
 187#define JSVAL_NULL              OBJECT_TO_JSVAL(0)
 188#define JSVAL_ZERO              INT_TO_JSVAL(0)
 189#define JSVAL_ONE               INT_TO_JSVAL(1)
 190#define JSVAL_FALSE             BOOLEAN_TO_JSVAL(JS_FALSE)
 191#define JSVAL_TRUE              BOOLEAN_TO_JSVAL(JS_TRUE)
 192
 193/*
 194 * Microseconds since the epoch, midnight, January 1, 1970 UTC.  See the
 195 * comment in jstypes.h regarding safe int64 usage.
 196 */
 197extern JS_PUBLIC_API(int64)
 198JS_Now(void);
 199
 200/* Don't want to export data, so provide accessors for non-inline jsvals. */
 201extern JS_PUBLIC_API(jsval)
 202JS_GetNaNValue(JSContext *cx);
 203
 204extern JS_PUBLIC_API(jsval)
 205JS_GetNegativeInfinityValue(JSContext *cx);
 206
 207extern JS_PUBLIC_API(jsval)
 208JS_GetPositiveInfinityValue(JSContext *cx);
 209
 210extern JS_PUBLIC_API(jsval)
 211JS_GetEmptyStringValue(JSContext *cx);
 212
 213/*
 214 * Format is a string of the following characters (spaces are insignificant),
 215 * specifying the tabulated type conversions:
 216 *
 217 *   b      JSBool          Boolean
 218 *   c      uint16/jschar   ECMA uint16, Unicode char
 219 *   i      int32           ECMA int32
 220 *   u      uint32          ECMA uint32
 221 *   j      int32           Rounded int32 (coordinate)
 222 *   d      jsdouble        IEEE double
 223 *   I      jsdouble        Integral IEEE double
 224 *   s      char *          C string
 225 *   S      JSString *      Unicode string, accessed by a JSString pointer
 226 *   W      jschar *        Unicode character vector, 0-terminated (W for wide)
 227 *   o      JSObject *      Object reference
 228 *   f      JSFunction *    Function private
 229 *   v      jsval           Argument value (no conversion)
 230 *   *      N/A             Skip this argument (no vararg)
 231 *   /      N/A             End of required arguments
 232 *
 233 * The variable argument list after format must consist of &b, &c, &s, e.g.,
 234 * where those variables have the types given above.  For the pointer types
 235 * char *, JSString *, and JSObject *, the pointed-at memory returned belongs
 236 * to the JS runtime, not to the calling native code.  The runtime promises
 237 * to keep this memory valid so long as argv refers to allocated stack space
 238 * (so long as the native function is active).
 239 *
 240 * Fewer arguments than format specifies may be passed only if there is a /
 241 * in format after the last required argument specifier and argc is at least
 242 * the number of required arguments.  More arguments than format specifies
 243 * may be passed without error; it is up to the caller to deal with trailing
 244 * unconverted arguments.
 245 */
 246extern JS_PUBLIC_API(JSBool)
 247JS_ConvertArguments(JSContext *cx, uintN argc, jsval *argv, const char *format,
 248                    ...);
 249
 250#ifdef va_start
 251extern JS_PUBLIC_API(JSBool)
 252JS_ConvertArgumentsVA(JSContext *cx, uintN argc, jsval *argv,
 253                      const char *format, va_list ap);
 254#endif
 255
 256/*
 257 * Inverse of JS_ConvertArguments: scan format and convert trailing arguments
 258 * into jsvals, GC-rooted if necessary by the JS stack.  Return null on error,
 259 * and a pointer to the new argument vector on success.  Also return a stack
 260 * mark on success via *markp, in which case the caller must eventually clean
 261 * up by calling JS_PopArguments.
 262 *
 263 * Note that the number of actual arguments supplied is specified exclusively
 264 * by format, so there is no argc parameter.
 265 */
 266extern JS_PUBLIC_API(jsval *)
 267JS_PushArguments(JSContext *cx, void **markp, const char *format, ...);
 268
 269#ifdef va_start
 270extern JS_PUBLIC_API(jsval *)
 271JS_PushArgumentsVA(JSContext *cx, void **markp, const char *format, va_list ap);
 272#endif
 273
 274extern JS_PUBLIC_API(void)
 275JS_PopArguments(JSContext *cx, void *mark);
 276
 277#ifdef JS_ARGUMENT_FORMATTER_DEFINED
 278
 279/*
 280 * Add and remove a format string handler for JS_{Convert,Push}Arguments{,VA}.
 281 * The handler function has this signature (see jspubtd.h):
 282 *
 283 *   JSBool MyArgumentFormatter(JSContext *cx, const char *format,
 284 *                              JSBool fromJS, jsval **vpp, va_list *app);
 285 *
 286 * It should return true on success, and return false after reporting an error
 287 * or detecting an already-reported error.
 288 *
 289 * For a given format string, for example "AA", the formatter is called from
 290 * JS_ConvertArgumentsVA like so:
 291 *
 292 *   formatter(cx, "AA...", JS_TRUE, &sp, &ap);
 293 *
 294 * sp points into the arguments array on the JS stack, while ap points into
 295 * the stdarg.h va_list on the C stack.  The JS_TRUE passed for fromJS tells
 296 * the formatter to convert zero or more jsvals at sp to zero or more C values
 297 * accessed via pointers-to-values at ap, updating both sp (via *vpp) and ap
 298 * (via *app) to point past the converted arguments and their result pointers
 299 * on the C stack.
 300 *
 301 * When called from JS_PushArgumentsVA, the formatter is invoked thus:
 302 *
 303 *   formatter(cx, "AA...", JS_FALSE, &sp, &ap);
 304 *
 305 * where JS_FALSE for fromJS means to wrap the C values at ap according to the
 306 * format specifier and store them at sp, updating ap and sp appropriately.
 307 *
 308 * The "..." after "AA" is the rest of the format string that was passed into
 309 * JS_{Convert,Push}Arguments{,VA}.  The actual format trailing substring used
 310 * in each Convert or PushArguments call is passed to the formatter, so that
 311 * one such function may implement several formats, in order to share code.
 312 *
 313 * Remove just forgets about any handler associated with format.  Add does not
 314 * copy format, it points at the string storage allocated by the caller, which
 315 * is typically a string constant.  If format is in dynamic storage, it is up
 316 * to the caller to keep the string alive until Remove is called.
 317 */
 318extern JS_PUBLIC_API(JSBool)
 319JS_AddArgumentFormatter(JSContext *cx, const char *format,
 320                        JSArgumentFormatter formatter);
 321
 322extern JS_PUBLIC_API(void)
 323JS_RemoveArgumentFormatter(JSContext *cx, const char *format);
 324
 325#endif /* JS_ARGUMENT_FORMATTER_DEFINED */
 326
 327extern JS_PUBLIC_API(JSBool)
 328JS_ConvertValue(JSContext *cx, jsval v, JSType type, jsval *vp);
 329
 330extern JS_PUBLIC_API(JSBool)
 331JS_ValueToObject(JSContext *cx, jsval v, JSObject **objp);
 332
 333extern JS_PUBLIC_API(JSFunction *)
 334JS_ValueToFunction(JSContext *cx, jsval v);
 335
 336extern JS_PUBLIC_API(JSFunction *)
 337JS_ValueToConstructor(JSContext *cx, jsval v);
 338
 339extern JS_PUBLIC_API(JSString *)
 340JS_ValueToString(JSContext *cx, jsval v);
 341
 342extern JS_PUBLIC_API(JSString *)
 343JS_ValueToSource(JSContext *cx, jsval v);
 344
 345extern JS_PUBLIC_API(JSBool)
 346JS_ValueToNumber(JSContext *cx, jsval v, jsdouble *dp);
 347
 348/*
 349 * Convert a value to a number, then to an int32, according to the ECMA rules
 350 * for ToInt32.
 351 */
 352extern JS_PUBLIC_API(JSBool)
 353JS_ValueToECMAInt32(JSContext *cx, jsval v, int32 *ip);
 354
 355/*
 356 * Convert a value to a number, then to a uint32, according to the ECMA rules
 357 * for ToUint32.
 358 */
 359extern JS_PUBLIC_API(JSBool)
 360JS_ValueToECMAUint32(JSContext *cx, jsval v, uint32 *ip);
 361
 362/*
 363 * Convert a value to a number, then to an int32 if it fits by rounding to
 364 * nearest; but failing with an error report if the double is out of range
 365 * or unordered.
 366 */
 367extern JS_PUBLIC_API(JSBool)
 368JS_ValueToInt32(JSContext *cx, jsval v, int32 *ip);
 369
 370/*
 371 * ECMA ToUint16, for mapping a jsval to a Unicode point.
 372 */
 373extern JS_PUBLIC_API(JSBool)
 374JS_ValueToUint16(JSContext *cx, jsval v, uint16 *ip);
 375
 376extern JS_PUBLIC_API(JSBool)
 377JS_ValueToBoolean(JSContext *cx, jsval v, JSBool *bp);
 378
 379extern JS_PUBLIC_API(JSType)
 380JS_TypeOfValue(JSContext *cx, jsval v);
 381
 382extern JS_PUBLIC_API(const char *)
 383JS_GetTypeName(JSContext *cx, JSType type);
 384
 385/************************************************************************/
 386
 387/*
 388 * Initialization, locking, contexts, and memory allocation.
 389 *
 390 * It is important that the first runtime and first context be created in a
 391 * single-threaded fashion, otherwise the behavior of the library is undefined.
 392 * See: http://developer.mozilla.org/en/docs/Category:JSAPI_Reference
 393 */
 394#define JS_NewRuntime       JS_Init
 395#define JS_DestroyRuntime   JS_Finish
 396#define JS_LockRuntime      JS_Lock
 397#define JS_UnlockRuntime    JS_Unlock
 398
 399extern JS_PUBLIC_API(JSRuntime *)
 400JS_NewRuntime(uint32 maxbytes);
 401
 402extern JS_PUBLIC_API(void)
 403JS_DestroyRuntime(JSRuntime *rt);
 404
 405extern JS_PUBLIC_API(void)
 406JS_ShutDown(void);
 407
 408JS_PUBLIC_API(void *)
 409JS_GetRuntimePrivate(JSRuntime *rt);
 410
 411JS_PUBLIC_API(void)
 412JS_SetRuntimePrivate(JSRuntime *rt, void *data);
 413
 414extern JS_PUBLIC_API(void)
 415JS_BeginRequest(JSContext *cx);
 416
 417extern JS_PUBLIC_API(void)
 418JS_EndRequest(JSContext *cx);
 419
 420/* Yield to pending GC operations, regardless of request depth */
 421extern JS_PUBLIC_API(void)
 422JS_YieldRequest(JSContext *cx);
 423
 424extern JS_PUBLIC_API(jsrefcount)
 425JS_SuspendRequest(JSContext *cx);
 426
 427extern JS_PUBLIC_API(void)
 428JS_ResumeRequest(JSContext *cx, jsrefcount saveDepth);
 429
 430#ifdef __cplusplus
 431JS_END_EXTERN_C
 432
 433class JSAutoRequest {
 434  public:
 435    JSAutoRequest(JSContext *cx) : mContext(cx), mSaveDepth(0) {
 436        JS_BeginRequest(mContext);
 437    }
 438    ~JSAutoRequest() {
 439        JS_EndRequest(mContext);
 440    }
 441
 442    void suspend() {
 443        mSaveDepth = JS_SuspendRequest(mContext);
 444    }
 445    void resume() {
 446        JS_ResumeRequest(mContext, mSaveDepth);
 447    }
 448
 449  protected:
 450    JSContext *mContext;
 451    jsrefcount mSaveDepth;
 452
 453#if 0
 454  private:
 455    static void *operator new(size_t) CPP_THROW_NEW { return 0; };
 456    static void operator delete(void *, size_t) { };
 457#endif
 458};
 459
 460class JSAutoSuspendRequest {
 461  public:
 462    JSAutoSuspendRequest(JSContext *cx) : mContext(cx), mSaveDepth(0) {
 463        if (mContext) {
 464            mSaveDepth = JS_SuspendRequest(mContext);
 465        }
 466    }
 467    ~JSAutoSuspendRequest() {
 468        resume();
 469    }
 470
 471    void resume() {
 472        if (mContext) {
 473            JS_ResumeRequest(mContext, mSaveDepth);
 474            mContext = 0;
 475        }
 476    }
 477
 478  protected:
 479    JSContext *mContext;
 480    jsrefcount mSaveDepth;
 481
 482#if 0
 483  private:
 484    static void *operator new(size_t) CPP_THROW_NEW { return 0; };
 485    static void operator delete(void *, size_t) { };
 486#endif
 487};
 488
 489JS_BEGIN_EXTERN_C
 490#endif
 491
 492extern JS_PUBLIC_API(void)
 493JS_Lock(JSRuntime *rt);
 494
 495extern JS_PUBLIC_API(void)
 496JS_Unlock(JSRuntime *rt);
 497
 498extern JS_PUBLIC_API(JSContextCallback)
 499JS_SetContextCallback(JSRuntime *rt, JSContextCallback cxCallback);
 500
 501extern JS_PUBLIC_API(JSContext *)
 502JS_NewContext(JSRuntime *rt, size_t stackChunkSize);
 503
 504extern JS_PUBLIC_API(void)
 505JS_DestroyContext(JSContext *cx);
 506
 507extern JS_PUBLIC_API(void)
 508JS_DestroyContextNoGC(JSContext *cx);
 509
 510extern JS_PUBLIC_API(void)
 511JS_DestroyContextMaybeGC(JSContext *cx);
 512
 513extern JS_PUBLIC_API(void *)
 514JS_GetContextPrivate(JSContext *cx);
 515
 516extern JS_PUBLIC_API(void)
 517JS_SetContextPrivate(JSContext *cx, void *data);
 518
 519extern JS_PUBLIC_API(JSRuntime *)
 520JS_GetRuntime(JSContext *cx);
 521
 522extern JS_PUBLIC_API(JSContext *)
 523JS_ContextIterator(JSRuntime *rt, JSContext **iterp);
 524
 525extern JS_PUBLIC_API(JSVersion)
 526JS_GetVersion(JSContext *cx);
 527
 528extern JS_PUBLIC_API(JSVersion)
 529JS_SetVersion(JSContext *cx, JSVersion version);
 530
 531extern JS_PUBLIC_API(const char *)
 532JS_VersionToString(JSVersion version);
 533
 534extern JS_PUBLIC_API(JSVersion)
 535JS_StringToVersion(const char *string);
 536
 537/*
 538 * JS options are orthogonal to version, and may be freely composed with one
 539 * another as well as with version.
 540 *
 541 * JSOPTION_VAROBJFIX is recommended -- see the comments associated with the
 542 * prototypes for JS_ExecuteScript, JS_EvaluateScript, etc.
 543 */
 544#define JSOPTION_STRICT         JS_BIT(0)       /* warn on dubious practice */
 545#define JSOPTION_WERROR         JS_BIT(1)       /* convert warning to error */
 546#define JSOPTION_VAROBJFIX      JS_BIT(2)       /* make JS_EvaluateScript use
 547                                                   the last object on its 'obj'
 548                                                   param's scope chain as the
 549                                                   ECMA 'variables object' */
 550#define JSOPTION_PRIVATE_IS_NSISUPPORTS \
 551                                JS_BIT(3)       /* context private data points
 552                                                   to an nsISupports subclass */
 553#define JSOPTION_COMPILE_N_GO   JS_BIT(4)       /* caller of JS_Compile*Script
 554                                                   promises to execute compiled
 555                                                   script once only; enables
 556                                                   compile-time scope chain
 557                                                   resolution of consts. */
 558#define JSOPTION_ATLINE         JS_BIT(5)       /* //@line number ["filename"]
 559                                                   option supported for the
 560                                                   XUL preprocessor and kindred
 561                                                   beasts. */
 562#define JSOPTION_XML            JS_BIT(6)       /* EMCAScript for XML support:
 563                                                   parse <!-- --> as a token,
 564                                                   not backward compatible with
 565                                                   the comment-hiding hack used
 566                                                   in HTML script tags. */
 567#define JSOPTION_NATIVE_BRANCH_CALLBACK \
 568                                JS_BIT(7)       /* the branch callback set by
 569                                                   JS_SetBranchCallback may be
 570                                                   called with a null script
 571                                                   parameter, by native code
 572                                                   that loops intensively.
 573                                                   Deprecated, use
 574                                                   JS_SetOperationCallback
 575                                                   instead */
 576#define JSOPTION_DONT_REPORT_UNCAUGHT \
 577                                JS_BIT(8)       /* When returning from the
 578                                                   outermost API call, prevent
 579                                                   uncaught exceptions from
 580                                                   being converted to error
 581                                                   reports */
 582
 583#define JSOPTION_RELIMIT        JS_BIT(9)       /* Throw exception on any
 584                                                   regular expression which
 585                                                   backtracks more than n^3
 586                                                   times, where n is length
 587                                                   of the input string */
 588#define JSOPTION_ANONFUNFIX     JS_BIT(10)      /* Disallow function () {} in
 589                                                   statement context per
 590                                                   ECMA-262 Edition 3. */
 591
 592#define JSOPTION_JIT            JS_BIT(11)      /* Enable JIT compilation. */
 593
 594#define JSOPTION_NO_SCRIPT_RVAL JS_BIT(12)      /* A promise to the compiler
 595                                                   that a null rval out-param
 596                                                   will be passed to each call
 597                                                   to JS_ExecuteScript. */
 598
 599extern JS_PUBLIC_API(uint32)
 600JS_GetOptions(JSContext *cx);
 601
 602extern JS_PUBLIC_API(uint32)
 603JS_SetOptions(JSContext *cx, uint32 options);
 604
 605extern JS_PUBLIC_API(uint32)
 606JS_ToggleOptions(JSContext *cx, uint32 options);
 607
 608extern JS_PUBLIC_API(const char *)
 609JS_GetImplementationVersion(void);
 610
 611extern JS_PUBLIC_API(JSObject *)
 612JS_GetGlobalObject(JSContext *cx);
 613
 614extern JS_PUBLIC_API(void)
 615JS_SetGlobalObject(JSContext *cx, JSObject *obj);
 616
 617/*
 618 * Initialize standard JS class constructors, prototypes, and any top-level
 619 * functions and constants associated with the standard classes (e.g. isNaN
 620 * for Number).
 621 *
 622 * NB: This sets cx's global object to obj if it was null.
 623 */
 624extern JS_PUBLIC_API(JSBool)
 625JS_InitStandardClasses(JSContext *cx, JSObject *obj);
 626
 627/*
 628 * Resolve id, which must contain either a string or an int, to a standard
 629 * class name in obj if possible, defining the class's constructor and/or
 630 * prototype and storing true in *resolved.  If id does not name a standard
 631 * class or a top-level property induced by initializing a standard class,
 632 * store false in *resolved and just return true.  Return false on error,
 633 * as usual for JSBool result-typed API entry points.
 634 *
 635 * This API can be called directly from a global object class's resolve op,
 636 * to define standard classes lazily.  The class's enumerate op should call
 637 * JS_EnumerateStandardClasses(cx, obj), to define eagerly during for..in
 638 * loops any classes not yet resolved lazily.
 639 */
 640extern JS_PUBLIC_API(JSBool)
 641JS_ResolveStandardClass(JSContext *cx, JSObject *obj, jsval id,
 642                        JSBool *resolved);
 643
 644extern JS_PUBLIC_API(JSBool)
 645JS_EnumerateStandardClasses(JSContext *cx, JSObject *obj);
 646
 647/*
 648 * Enumerate any already-resolved standard class ids into ida, or into a new
 649 * JSIdArray if ida is null.  Return the augmented array on success, null on
 650 * failure with ida (if it was non-null on entry) destroyed.
 651 */
 652extern JS_PUBLIC_API(JSIdArray *)
 653JS_EnumerateResolvedStandardClasses(JSContext *cx, JSObject *obj,
 654                                    JSIdArray *ida);
 655
 656extern JS_PUBLIC_API(JSBool)
 657JS_GetClassObject(JSContext *cx, JSObject *obj, JSProtoKey key,
 658                  JSObject **objp);
 659
 660extern JS_PUBLIC_API(JSObject *)
 661JS_GetScopeChain(JSContext *cx);
 662
 663extern JS_PUBLIC_API(JSObject *)
 664JS_GetGlobalForObject(JSContext *cx, JSObject *obj);
 665
 666/*
 667 * Macros to hide interpreter stack layout details from a JSFastNative using
 668 * its jsval *vp parameter. The stack layout underlying invocation can't change
 669 * without breaking source and binary compatibility (argv[-2] is well-known to
 670 * be the callee jsval, and argv[-1] is as well known to be |this|).
 671 *
 672 * Note well: However, argv[-1] may be JSVAL_NULL where with slow natives it
 673 * is the global object, so embeddings implementing fast natives *must* call
 674 * JS_THIS or JS_THIS_OBJECT and test for failure indicated by a null return,
 675 * which should propagate as a false return from native functions and hooks.
 676 *
 677 * To reduce boilerplace checks, JS_InstanceOf and JS_GetInstancePrivate now
 678 * handle a null obj parameter by returning false (throwing a TypeError if
 679 * given non-null argv), so most native functions that type-check their |this|
 680 * parameter need not add null checking.
 681 *
 682 * NB: there is an anti-dependency between JS_CALLEE and JS_SET_RVAL: native
 683 * methods that may inspect their callee must defer setting their return value
 684 * until after any such possible inspection. Otherwise the return value will be
 685 * inspected instead of the callee function object.
 686 *
 687 * WARNING: These are not (yet) mandatory macros, but new code outside of the
 688 * engine should use them. In the Mozilla 2.0 milestone their definitions may
 689 * change incompatibly.
 690 */
 691#define JS_CALLEE(cx,vp)        ((vp)[0])
 692#define JS_ARGV_CALLEE(argv)    ((argv)[-2])
 693#define JS_THIS(cx,vp)          JS_ComputeThis(cx, vp)
 694#define JS_THIS_OBJECT(cx,vp)   ((JSObject *) JS_THIS(cx,vp))
 695#define JS_ARGV(cx,vp)          ((vp) + 2)
 696#define JS_RVAL(cx,vp)          (*(vp))
 697#define JS_SET_RVAL(cx,vp,v)    (*(vp) = (v))
 698
 699extern JS_PUBLIC_API(jsval)
 700JS_ComputeThis(JSContext *cx, jsval *vp);
 701
 702extern JS_PUBLIC_API(void *)
 703JS_malloc(JSContext *cx, size_t nbytes);
 704
 705extern JS_PUBLIC_API(void *)
 706JS_realloc(JSContext *cx, void *p, size_t nbytes);
 707
 708extern JS_PUBLIC_API(void)
 709JS_free(JSContext *cx, void *p);
 710
 711extern JS_PUBLIC_API(char *)
 712JS_strdup(JSContext *cx, const char *s);
 713
 714extern JS_PUBLIC_API(jsdouble *)
 715JS_NewDouble(JSContext *cx, jsdouble d);
 716
 717extern JS_PUBLIC_API(JSBool)
 718JS_NewDoubleValue(JSContext *cx, jsdouble d, jsval *rval);
 719
 720extern JS_PUBLIC_API(JSBool)
 721JS_NewNumberValue(JSContext *cx, jsdouble d, jsval *rval);
 722
 723/*
 724 * A JS GC root is a pointer to a JSObject *, JSString *, or jsdouble * that
 725 * itself points into the GC heap (more recently, we support this extension:
 726 * a root may be a pointer to a jsval v for which JSVAL_IS_GCTHING(v) is true).
 727 *
 728 * Therefore, you never pass JSObject *obj to JS_AddRoot(cx, obj).  You always
 729 * call JS_AddRoot(cx, &obj), passing obj by reference.  And later, before obj
 730 * or the structure it is embedded within goes out of scope or is freed, you
 731 * must call JS_RemoveRoot(cx, &obj).
 732 *
 733 * Also, use JS_AddNamedRoot(cx, &structPtr->memberObj, "structPtr->memberObj")
 734 * in preference to JS_AddRoot(cx, &structPtr->memberObj), in order to identify
 735 * roots by their source callsites.  This way, you can find the callsite while
 736 * debugging if you should fail to do JS_RemoveRoot(cx, &structPtr->memberObj)
 737 * before freeing structPtr's memory.
 738 */
 739extern JS_PUBLIC_API(JSBool)
 740JS_AddRoot(JSContext *cx, void *rp);
 741
 742#ifdef NAME_ALL_GC_ROOTS
 743#define JS_DEFINE_TO_TOKEN(def) #def
 744#define JS_DEFINE_TO_STRING(def) JS_DEFINE_TO_TOKEN(def)
 745#define JS_AddRoot(cx,rp) JS_AddNamedRoot((cx), (rp), (__FILE__ ":" JS_TOKEN_TO_STRING(__LINE__))
 746#endif
 747
 748extern JS_PUBLIC_API(JSBool)
 749JS_AddNamedRoot(JSContext *cx, void *rp, const char *name);
 750
 751extern JS_PUBLIC_API(JSBool)
 752JS_AddNamedRootRT(JSRuntime *rt, void *rp, const char *name);
 753
 754extern JS_PUBLIC_API(JSBool)
 755JS_RemoveRoot(JSContext *cx, void *rp);
 756
 757extern JS_PUBLIC_API(JSBool)
 758JS_RemoveRootRT(JSRuntime *rt, void *rp);
 759
 760/*
 761 * The last GC thing of each type (object, string, double, external string
 762 * types) created on a given context is kept alive until another thing of the
 763 * same type is created, using a newborn root in the context.  These newborn
 764 * roots help native code protect newly-created GC-things from GC invocations
 765 * activated before those things can be rooted using local or global roots.
 766 *
 767 * However, the newborn roots can also entrain great gobs of garbage, so the
 768 * JS_GC entry point clears them for the context on which GC is being forced.
 769 * Embeddings may need to do likewise for all contexts.
 770 *
 771 * See the scoped local root API immediately below for a better way to manage
 772 * newborns in cases where native hooks (functions, getters, setters, etc.)
 773 * create many GC-things, potentially without connecting them to predefined
 774 * local roots such as *rval or argv[i] in an active native function.  Using
 775 * JS_EnterLocalRootScope disables updating of the context's per-gc-thing-type
 776 * newborn roots, until control flow unwinds and leaves the outermost nesting
 777 * local root scope.
 778 */
 779extern JS_PUBLIC_API(void)
 780JS_ClearNewbornRoots(JSContext *cx);
 781
 782/*
 783 * Scoped local root management allows native functions, getter/setters, etc.
 784 * to avoid worrying about the newborn root pigeon-holes, overloading local
 785 * roots allocated in argv and *rval, or ending up having to call JS_Add*Root
 786 * and JS_RemoveRoot to manage global roots temporarily.
 787 *
 788 * Instead, calling JS_EnterLocalRootScope and JS_LeaveLocalRootScope around
 789 * the body of the native hook causes the engine to allocate a local root for
 790 * each newborn created in between the two API calls, using a local root stack
 791 * associated with cx.  For example:
 792 *
 793 *    JSBool
 794 *    my_GetProperty(JSContext *cx, JSObject *obj, jsval id, jsval *vp)
 795 *    {
 796 *        JSBool ok;
 797 *
 798 *        if (!JS_EnterLocalRootScope(cx))
 799 *            return JS_FALSE;
 800 *        ok = my_GetPropertyBody(cx, obj, id, vp);
 801 *        JS_LeaveLocalRootScope(cx);
 802 *        return ok;
 803 *    }
 804 *
 805 * NB: JS_LeaveLocalRootScope must be called once for every prior successful
 806 * call to JS_EnterLocalRootScope.  If JS_EnterLocalRootScope fails, you must
 807 * not make the matching JS_LeaveLocalRootScope call.
 808 *
 809 * JS_LeaveLocalRootScopeWithResult(cx, rval) is an alternative way to leave
 810 * a local root scope that protects a result or return value, by effectively
 811 * pushing it in the caller's local root scope.
 812 *
 813 * In case a native hook allocates many objects or other GC-things, but the
 814 * native protects some of those GC-things by storing them as property values
 815 * in an object that is itself protected, the hook can call JS_ForgetLocalRoot
 816 * to free the local root automatically pushed for the now-protected GC-thing.
 817 *
 818 * JS_ForgetLocalRoot works on any GC-thing allocated in the current local
 819 * root scope, but it's more time-efficient when called on references to more
 820 * recently created GC-things.  Calling it successively on other than the most
 821 * recently allocated GC-thing will tend to average the time inefficiency, and
 822 * may risk O(n^2) growth rate, but in any event, you shouldn't allocate too
 823 * many local roots if you can root as you go (build a tree of objects from
 824 * the top down, forgetting each latest-allocated GC-thing immediately upon
 825 * linking it to its parent).
 826 */
 827extern JS_PUBLIC_API(JSBool)
 828JS_EnterLocalRootScope(JSContext *cx);
 829
 830extern JS_PUBLIC_API(void)
 831JS_LeaveLocalRootScope(JSContext *cx);
 832
 833extern JS_PUBLIC_API(void)
 834JS_LeaveLocalRootScopeWithResult(JSContext *cx, jsval rval);
 835
 836extern JS_PUBLIC_API(void)
 837JS_ForgetLocalRoot(JSContext *cx, void *thing);
 838
 839#ifdef __cplusplus
 840JS_END_EXTERN_C
 841
 842class JSAutoLocalRootScope {
 843  public:
 844    JSAutoLocalRootScope(JSContext *cx) : mContext(cx) {
 845        JS_EnterLocalRootScope(mContext);
 846    }
 847    ~JSAutoLocalRootScope() {
 848        JS_LeaveLocalRootScope(mContext);
 849    }
 850
 851    void forget(void *thing) {
 852        JS_ForgetLocalRoot(mContext, thing);
 853    }
 854
 855  protected:
 856    JSContext *mContext;
 857
 858#if 0
 859  private:
 860    static void *operator new(size_t) CPP_THROW_NEW { return 0; };
 861    static void operator delete(void *, size_t) { };
 862#endif
 863};
 864
 865JS_BEGIN_EXTERN_C
 866#endif
 867
 868#ifdef DEBUG
 869extern JS_PUBLIC_API(void)
 870JS_DumpNamedRoots(JSRuntime *rt,
 871                  void (*dump)(const char *name, void *rp, void *data),
 872                  void *data);
 873#endif
 874
 875/*
 876 * Call JS_MapGCRoots to map the GC's roots table using map(rp, name, data).
 877 * The root is pointed at by rp; if the root is unnamed, name is null; data is
 878 * supplied from the third parameter to JS_MapGCRoots.
 879 *
 880 * The map function should return JS_MAP_GCROOT_REMOVE to cause the currently
 881 * enumerated root to be removed.  To stop enumeration, set JS_MAP_GCROOT_STOP
 882 * in the return value.  To keep on mapping, return JS_MAP_GCROOT_NEXT.  These
 883 * constants are flags; you can OR them together.
 884 *
 885 * This function acquires and releases rt's GC lock around the mapping of the
 886 * roots table, so the map function should run to completion in as few cycles
 887 * as possible.  Of course, map cannot call JS_GC, JS_MaybeGC, JS_BeginRequest,
 888 * or any JS API entry point that acquires locks, without double-tripping or
 889 * deadlocking on the GC lock.
 890 *
 891 * JS_MapGCRoots returns the count of roots that were successfully mapped.
 892 */
 893#define JS_MAP_GCROOT_NEXT      0       /* continue mapping entries */
 894#define JS_MAP_GCROOT_STOP      1       /* stop mapping entries */
 895#define JS_MAP_GCROOT_REMOVE    2       /* remove and free the current entry */
 896
 897typedef intN
 898(* JSGCRootMapFun)(void *rp, const char *name, void *data);
 899
 900extern JS_PUBLIC_API(uint32)
 901JS_MapGCRoots(JSRuntime *rt, JSGCRootMapFun map, void *data);
 902
 903extern JS_PUBLIC_API(JSBool)
 904JS_LockGCThing(JSContext *cx, void *thing);
 905
 906extern JS_PUBLIC_API(JSBool)
 907JS_LockGCThingRT(JSRuntime *rt, void *thing);
 908
 909extern JS_PUBLIC_API(JSBool)
 910JS_UnlockGCThing(JSContext *cx, void *thing);
 911
 912extern JS_PUBLIC_API(JSBool)
 913JS_UnlockGCThingRT(JSRuntime *rt, void *thing);
 914
 915/*
 916 * Register externally maintained GC roots.
 917 *
 918 * traceOp: the trace operation. For each root the implementation should call
 919 *          JS_CallTracer whenever the root contains a traceable thing.
 920 * data:    the data argument to pass to each invocation of traceOp.
 921 */
 922extern JS_PUBLIC_API(void)
 923JS_SetExtraGCRoots(JSRuntime *rt, JSTraceDataOp traceOp, void *data);
 924
 925/*
 926 * For implementors of JSMarkOp. All new code should implement JSTraceOp
 927 * instead.
 928 */
 929extern JS_PUBLIC_API(void)
 930JS_MarkGCThing(JSContext *cx, void *thing, const char *name, void *arg);
 931
 932/*
 933 * JS_CallTracer API and related macros for implementors of JSTraceOp, to
 934 * enumerate all references to traceable things reachable via a property or
 935 * other strong ref identified for debugging purposes by name or index or
 936 * a naming callback.
 937 *
 938 * By definition references to traceable things include non-null pointers
 939 * to JSObject, JSString and jsdouble and corresponding jsvals.
 940 *
 941 * See the JSTraceOp typedef in jspubtd.h.
 942 */
 943
 944/* Trace kinds to pass to JS_Tracing. */
 945#define JSTRACE_OBJECT  0
 946#define JSTRACE_DOUBLE  1
 947#define JSTRACE_STRING  2
 948
 949/*
 950 * Use the following macros to check if a particular jsval is a traceable
 951 * thing and to extract the thing and its kind to pass to JS_CallTracer.
 952 */
 953#define JSVAL_IS_TRACEABLE(v)   (JSVAL_IS_GCTHING(v) && !JSVAL_IS_NULL(v))
 954#define JSVAL_TO_TRACEABLE(v)   (JSVAL_TO_GCTHING(v))
 955#define JSVAL_TRACE_KIND(v)     (JSVAL_TAG(v) >> 1)
 956
 957JS_STATIC_ASSERT(JSVAL_TRACE_KIND(JSVAL_OBJECT) == JSTRACE_OBJECT);
 958JS_STATIC_ASSERT(JSVAL_TRACE_KIND(JSVAL_DOUBLE) == JSTRACE_DOUBLE);
 959JS_STATIC_ASSERT(JSVAL_TRACE_KIND(JSVAL_STRING) == JSTRACE_STRING);
 960
 961struct JSTracer {
 962    JSContext           *context;
 963    JSTraceCallback     callback;
 964#ifdef DEBUG
 965    JSTraceNamePrinter  debugPrinter;
 966    const void          *debugPrintArg;
 967    size_t              debugPrintIndex;
 968#endif
 969};
 970
 971/*
 972 * The method to call on each reference to a traceable thing stored in a
 973 * particular JSObject or other runtime structure. With DEBUG defined the
 974 * caller before calling JS_CallTracer must initialize JSTracer fields
 975 * describing the reference using the macros below.
 976 */
 977extern JS_PUBLIC_API(void)
 978JS_CallTracer(JSTracer *trc, void *thing, uint32 kind);
 979
 980/*
 981 * Set debugging information about a reference to a traceable thing to prepare
 982 * for the following call to JS_CallTracer.
 983 *
 984 * When printer is null, arg must be const char * or char * C string naming
 985 * the reference and index must be either (size_t)-1 indicating that the name
 986 * alone describes the reference or it must be an index into some array vector
 987 * that stores the reference.
 988 *
 989 * When printer callback is not null, the arg and index arguments are
 990 * available to the callback as debugPrinterArg and debugPrintIndex fields
 991 * of JSTracer.
 992 *
 993 * The storage for name or callback's arguments needs to live only until
 994 * the following call to JS_CallTracer returns.
 995 */
 996#ifdef DEBUG
 997# define JS_SET_TRACING_DETAILS(trc, printer, arg, index)                     \
 998    JS_BEGIN_MACRO                                                            \
 999        (trc)->debugPrinter = (printer);                                      \
1000        (trc)->debugPrintArg = (arg);                                         \
1001        (trc)->debugPrintIndex = (index);                                     \
1002    JS_END_MACRO
1003#else
1004# define JS_SET_TRACING_DETAILS(trc, printer, arg, index)                     \
1005    JS_BEGIN_MACRO                                                            \
1006    JS_END_MACRO
1007#endif
1008
1009/*
1010 * Convenience macro to describe the argument of JS_CallTracer using C string
1011 * and index.
1012 */
1013# define JS_SET_TRACING_INDEX(trc, name, index)                               \
1014    JS_SET_TRACING_DETAILS(trc, NULL, name, index)
1015
1016/*
1017 * Convenience macro to describe the argument of JS_CallTracer using C string.
1018 */
1019# define JS_SET_TRACING_NAME(trc, name)                                       \
1020    JS_SET_TRACING_DETAILS(trc, NULL, name, (size_t)-1)
1021
1022/*
1023 * Convenience macro to invoke JS_CallTracer using C string as the name for
1024 * the reference to a traceable thing.
1025 */
1026# define JS_CALL_TRACER(trc, thing, kind, name)                               \
1027    JS_BEGIN_MACRO                                                            \
1028        JS_SET_TRACING_NAME(trc, name);                                       \
1029        JS_CallTracer((trc), (thing), (kind));                                \
1030    JS_END_MACRO
1031
1032/*
1033 * Convenience macros to invoke JS_CallTracer when jsval represents a
1034 * reference to a traceable thing.
1035 */
1036#define JS_CALL_VALUE_TRACER(trc, val, name)                                  \
1037    JS_BEGIN_MACRO                                                            \
1038        if (JSVAL_IS_TRACEABLE(val)) {                                        \
1039            JS_CALL_TRACER((trc), JSVAL_TO_GCTHING(val),                      \
1040                           JSVAL_TRACE_KIND(val), name);                      \
1041        }                                                                     \
1042    JS_END_MACRO
1043
1044#define JS_CALL_OBJECT_TRACER(trc, object, name)                              \
1045    JS_BEGIN_MACRO                                                            \
1046        JSObject *obj_ = (object);                                            \
1047        JS_ASSERT(obj_);                                                      \
1048        JS_CALL_TRACER((trc), obj_, JSTRACE_OBJECT, name);                    \
1049    JS_END_MACRO
1050
1051#define JS_CALL_STRING_TRACER(trc, string, name)                              \
1052    JS_BEGIN_MACRO                                                            \
1053        JSString *str_ = (string);                                            \
1054        JS_ASSERT(str_);                                                      \
1055        JS_CALL_TRACER((trc), str_, JSTRACE_STRING, name);                    \
1056    JS_END_MACRO
1057
1058#define JS_CALL_DOUBLE_TRACER(trc, number, name)                              \
1059    JS_BEGIN_MACRO                                                            \
1060        jsdouble *num_ = (number);                                            \
1061        JS_ASSERT(num_);                                                      \
1062        JS_CALL_TRACER((trc), num_, JSTRACE_DOUBLE, name);                    \
1063    JS_END_MACRO
1064
1065/*
1066 * API for JSTraceCallback implementations.
1067 */
1068# define JS_TRACER_INIT(trc, cx_, callback_)                                  \
1069    JS_BEGIN_MACRO                                                            \
1070        (trc)->context = (cx_);                                               \
1071        (trc)->callback = (callback_);                                        \
1072        JS_SET_TRACING_DETAILS(trc, NULL, NULL, (size_t)-1);                  \
1073    JS_END_MACRO
1074
1075extern JS_PUBLIC_API(void)
1076JS_TraceChildren(JSTracer *trc, void *thing, uint32 kind);
1077
1078extern JS_PUBLIC_API(void)
1079JS_TraceRuntime(JSTracer *trc);
1080
1081#ifdef DEBUG
1082
1083extern JS_PUBLIC_API(void)
1084JS_PrintTraceThingInfo(char *buf, size_t bufsize, JSTracer *trc,
1085                       void *thing, uint32 kind, JSBool includeDetails);
1086
1087/*
1088 * DEBUG-only method to dump the object graph of heap-allocated things.
1089 *
1090 * fp:              file for the dump output.
1091 * start:           when non-null, dump only things reachable from start
1092 *                  thing. Otherwise dump all things reachable from the
1093 *                  runtime roots.
1094 * startKind:       trace kind of start if start is not null. Must be 0 when
1095 *                  start is null.
1096 * thingToFind:     dump only paths in the object graph leading to thingToFind
1097 *                  when non-null.
1098 * maxDepth:        the upper bound on the number of edges to descend from the
1099 *                  graph roots.
1100 * thingToIgnore:   thing to ignore during the graph traversal when non-null.
1101 */
1102extern JS_PUBLIC_API(JSBool)
1103JS_DumpHeap(JSContext *cx, FILE *fp, void* startThing, uint32 startKind,
1104            void *thingToFind, size_t maxDepth, void *thingToIgnore);
1105
1106#endif
1107
1108/*
1109 * Garbage collector API.
1110 */
1111extern JS_PUBLIC_API(void)
1112JS_GC(JSContext *cx);
1113
1114extern JS_PUBLIC_API(void)
1115JS_MaybeGC(JSContext *cx);
1116
1117extern JS_PUBLIC_API(JSGCCallback)
1118JS_SetGCCallback(JSContext *cx, JSGCCallback cb);
1119
1120extern JS_PUBLIC_API(JSGCCallback)
1121JS_SetGCCallbackRT(JSRuntime *rt, JSGCCallback cb);
1122
1123extern JS_PUBLIC_API(JSBool)
1124JS_IsGCMarkingTracer(JSTracer *trc);
1125
1126extern JS_PUBLIC_API(JSBool)
1127JS_IsAboutToBeFinalized(JSContext *cx, void *thing);
1128
1129typedef enum JSGCParamKey {
1130    /* Maximum nominal heap before last ditch GC. */
1131    JSGC_MAX_BYTES          = 0,
1132
1133    /* Number of JS_malloc bytes before last ditch GC. */
1134    JSGC_MAX_MALLOC_BYTES   = 1,
1135
1136    /* Hoard stackPools for this long, in ms, default is 30 seconds. */
1137    JSGC_STACKPOOL_LIFESPAN = 2
1138} JSGCParamKey;
1139
1140extern JS_PUBLIC_API(void)
1141JS_SetGCParameter(JSRuntime *rt, JSGCParamKey key, uint32 value);
1142
1143/*
1144 * Add a finalizer for external strings created by JS_NewExternalString (see
1145 * below) using a type-code returned from this function, and that understands
1146 * how to free or release the memory pointed at by JS_GetStringChars(str).
1147 *
1148 * Return a nonnegative type index if there is room for finalizer in the
1149 * global GC finalizers table, else return -1.  If the engine is compiled
1150 * JS_THREADSAFE and used in a multi-threaded environment, this function must
1151 * be invoked on the primordial thread only, at startup -- or else the entire
1152 * program must single-thread itself while loading a module that calls this
1153 * function.
1154 */
1155extern JS_PUBLIC_API(intN)
1156JS_AddExternalStringFinalizer(JSStringFinalizeOp finalizer);
1157
1158/*
1159 * Remove finalizer from the global GC finalizers table, returning its type
1160 * code if found, -1 if not found.
1161 *
1162 * As with JS_AddExternalStringFinalizer, there is a threading restriction
1163 * if you compile the engine JS_THREADSAFE: this function may be called for a
1164 * given finalizer pointer on only one thread; different threads may call to
1165 * remove distinct finalizers safely.
1166 *
1167 * You must ensure that all strings with finalizer's type have been collected
1168 * before calling this function.  Otherwise, string data will be leaked by the
1169 * GC, for want of a finalizer to call.
1170 */
1171extern JS_PUBLIC_API(intN)
1172JS_RemoveExternalStringFinalizer(JSStringFinalizeOp finalizer);
1173
1174/*
1175 * Create a new JSString whose chars member refers to external memory, i.e.,
1176 * memory requiring special, type-specific finalization.  The type code must
1177 * be a nonnegative return value from JS_AddExternalStringFinalizer.
1178 */
1179extern JS_PUBLIC_API(JSString *)
1180JS_NewExternalString(JSContext *cx, jschar *chars, size_t length, intN type);
1181
1182/*
1183 * Returns the external-string finalizer index for this string, or -1 if it is
1184 * an "internal" (native to JS engine) string.
1185 */
1186extern JS_PUBLIC_API(intN)
1187JS_GetExternalStringGCType(JSRuntime *rt, JSString *str);
1188
1189/*
1190 * Sets maximum (if stack grows upward) or minimum (downward) legal stack byte
1191 * address in limitAddr for the thread or process stack used by cx.  To disable
1192 * stack size checking, pass 0 for limitAddr.
1193 */
1194extern JS_PUBLIC_API(void)
1195JS_SetThreadStackLimit(JSContext *cx, jsuword limitAddr);
1196
1197/*
1198 * Set the quota on the number of bytes that stack-like data structures can
1199 * use when the runtime compiles and executes scripts. These structures
1200 * consume heap space, so JS_SetThreadStackLimit does not bound their size.
1201 * The default quota is 32MB which is quite generous.
1202 *
1203 * The function must be called before any script compilation or execution API
1204 * calls, i.e. either immediately after JS_NewContext or from JSCONTEXT_NEW
1205 * context callback.
1206 */
1207extern JS_PUBLIC_API(void)
1208JS_SetScriptStackQuota(JSContext *cx, size_t quota);
1209
1210#define JS_DEFAULT_SCRIPT_STACK_QUOTA   ((size_t) 0x2000000)
1211
1212/************************************************************************/
1213
1214/*
1215 * Classes, objects, and properties.
1216 */
1217
1218/* For detailed comments on the function pointer types, see jspubtd.h. */
1219struct JSClass {
1220    const char          *name;
1221    uint32              flags;
1222
1223    /* Mandatory non-null function pointer members. */
1224    JSPropertyOp        addProperty;
1225    JSPropertyOp        delProperty;
1226    JSPropertyOp        getProperty;
1227    JSPropertyOp        setProperty;
1228    JSEnumerateOp       enumerate;
1229    JSResolveOp         resolve;
1230    JSConvertOp         convert;
1231    JSFinalizeOp        finalize;
1232
1233    /* Optionally non-null members start here. */
1234    JSGetObjectOps      getObjectOps;
1235    JSCheckAccessOp     checkAccess;
1236    JSNative            call;
1237    JSNative            construct;
1238    JSXDRObjectOp       xdrObject;
1239    JSHasInstanceOp     hasInstance;
1240    JSMarkOp            mark;
1241    JSReserveSlotsOp    reserveSlots;
1242};
1243
1244struct JSExtendedClass {
1245    JSClass             base;
1246    JSEqualityOp        equality;
1247    JSObjectOp          outerObject;
1248    JSObjectOp          innerObject;
1249    JSIteratorOp        iteratorObject;
1250    JSObjectOp          wrappedObject;          /* NB: infallible, null
1251                                                   returns are treated as
1252                                                   the original object */
1253    void                (*reserved0)(void);
1254    void                (*reserved1)(void);
1255    void                (*reserved2)(void);
1256};
1257
1258#define JSCLASS_HAS_PRIVATE             (1<<0)  /* objects have private slot */
1259#define JSCLASS_NEW_ENUMERATE           (1<<1)  /* has JSNewEnumerateOp hook */
1260#define JSCLASS_NEW_RESOLVE             (1<<2)  /* has JSNewResolveOp hook */
1261#define JSCLASS_PRIVATE_IS_NSISUPPORTS  (1<<3)  /* private is (nsISupports *) */
1262#define JSCLASS_SHARE_ALL_PROPERTIES    (1<<4)  /* all properties are SHARED */
1263#define JSCLASS_NEW_RESOLVE_GETS_START  (1<<5)  /* JSNewResolveOp gets starting
1264                                                 

Large files files are truncated, but you can click here to view the full file