/js/lib/Socket.IO-node/support/expresso/deps/jscoverage/js/jsapi.h
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