LCOV - app.info - js/src/jsapi.h

LCOV - code coverage report
| Current view: | directory - js/src - jsapi.h (source / functions) |  | Found | Hit | Coverage |
| Test: | app.info | Lines: | 536 | 466 | 86.9 %
| Date: | 2012-04-07 | Functions: | 253 | 227 | 89.7 %

           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                 :
          47                 : #include "mozilla/StandardInteger.h"
          48                 :
          49                 : #include <stddef.h>
          50                 : #include <stdio.h>
          51                 : #include "js-config.h"
          52                 : #include "jspubtd.h"
          53                 : #include "jsutil.h"
          54                 : #include "jsval.h"
          55                 :
          56                 : #include "js/Utility.h"
          57                 :
          58                 : #ifdef __cplusplus
          59                 : #include "jsalloc.h"
          60                 : #include "js/Vector.h"
          61                 : #include "mozilla/Attributes.h"
          62                 : #endif
          63                 :
          64                 : /************************************************************************/
          65                 :
          66                 : /* JS::Value can store a full int32_t. */
          67                 : #define JSVAL_INT_BITS          32
          68                 : #define JSVAL_INT_MIN           ((int32_t)0x80000000)
          69                 : #define JSVAL_INT_MAX           ((int32_t)0x7fffffff)
          70                 :
          71                 : /************************************************************************/
          72                 :
          73                 : #define JS_Assert MOZ_Assert
          74                 :
          75                 : #ifdef __cplusplus
          76                 : namespace JS {
          77                 :
          78                 : /*
          79                 :  * Protecting non-jsval, non-JSObject *, non-JSString * values from collection
          80                 :  *
          81                 :  * Most of the time, the garbage collector's conservative stack scanner works
          82                 :  * behind the scenes, finding all live values and protecting them from being
          83                 :  * collected. However, when JSAPI client code obtains a pointer to data the
          84                 :  * scanner does not know about, owned by an object the scanner does know about,
          85                 :  * Care Must Be Taken.
          86                 :  *
          87                 :  * The scanner recognizes only a select set of types: pointers to JSObjects and
          88                 :  * similar things (JSFunctions, and so on), pointers to JSStrings, and jsvals.
          89                 :  * So while the scanner finds all live |JSString| pointers, it does not notice
          90                 :  * |jschar| pointers.
          91                 :  *
          92                 :  * So suppose we have:
          93                 :  *
          94                 :  *   void f(JSString *str) {
          95                 :  *     const jschar *ch = JS_GetStringCharsZ(str);
          96                 :  *     ... do stuff with ch, but no uses of str ...;
          97                 :  *   }
          98                 :  *
          99                 :  * After the call to |JS_GetStringCharsZ|, there are no further uses of
         100                 :  * |str|, which means that the compiler is within its rights to not store
         101                 :  * it anywhere. But because the stack scanner will not notice |ch|, there
         102                 :  * is no longer any live value in this frame that would keep the string
         103                 :  * alive. If |str| is the last reference to that |JSString|, and the
         104                 :  * collector runs while we are using |ch|, the string's array of |jschar|s
         105                 :  * may be freed out from under us.
         106                 :  *
         107                 :  * Note that there is only an issue when 1) we extract a thing X the scanner
         108                 :  * doesn't recognize from 2) a thing Y the scanner does recognize, and 3) if Y
         109                 :  * gets garbage-collected, then X gets freed. If we have code like this:
         110                 :  *
         111                 :  *   void g(JSObject *obj) {
         112                 :  *     jsval x;
         113                 :  *     JS_GetProperty(obj, "x", &x);
         114                 :  *     ... do stuff with x ...
         115                 :  *   }
         116                 :  *
         117                 :  * there's no problem, because the value we've extracted, x, is a jsval, a
         118                 :  * type that the conservative scanner recognizes.
         119                 :  *
         120                 :  * Conservative GC frees us from the obligation to explicitly root the types it
         121                 :  * knows about, but when we work with derived values like |ch|, we must root
         122                 :  * their owners, as the derived value alone won't keep them alive.
         123                 :  *
         124                 :  * A JS::Anchor is a kind of GC root that allows us to keep the owners of
         125                 :  * derived values like |ch| alive throughout the Anchor's lifetime. We could
         126                 :  * fix the above code as follows:
         127                 :  *
         128                 :  *   void f(JSString *str) {
         129                 :  *     JS::Anchor<JSString *> a_str(str);
         130                 :  *     const jschar *ch = JS_GetStringCharsZ(str);
         131                 :  *     ... do stuff with ch, but no uses of str ...;
         132                 :  *   }
         133                 :  *
         134                 :  * This simply ensures that |str| will be live until |a_str| goes out of scope.
         135                 :  * As long as we don't retain a pointer to the string's characters for longer
         136                 :  * than that, we have avoided all garbage collection hazards.
         137                 :  */
         138                 : template<typename T> class AnchorPermitted;
         139             228 : template<> class AnchorPermitted<JSObject *> { };
         140                 : template<> class AnchorPermitted<const JSObject *> { };
         141                 : template<> class AnchorPermitted<JSFunction *> { };
         142                 : template<> class AnchorPermitted<const JSFunction *> { };
         143          708994 : template<> class AnchorPermitted<JSString *> { };
         144                 : template<> class AnchorPermitted<const JSString *> { };
         145                 : template<> class AnchorPermitted<Value> { };
         146                 : template<> class AnchorPermitted<const JSScript *> { };
         147           38261 : template<> class AnchorPermitted<JSScript *> { };
         148                 :
         149                 : template<typename T>
         150                 : class Anchor: AnchorPermitted<T>
         151                 : {
         152                 :   public:
         153           38263 :     Anchor() { }
         154          709220 :     explicit Anchor(T t) { hold = t; }
         155                 :     inline ~Anchor();
         156           38272 :     T &get() { return hold; }
         157                 :     const T &get() const { return hold; }
         158           10400 :     void set(const T &t) { hold = t; }
         159           38261 :     void operator=(const T &t) { hold = t; }
         160                 :     void clear() { hold = 0; }
         161                 :   private:
         162                 :     T hold;
         163                 :     Anchor(const Anchor &) MOZ_DELETE;
         164                 :     const Anchor &operator=(const Anchor &) MOZ_DELETE;
         165                 : };
         166                 :
         167                 : #ifdef __GNUC__
         168                 : template<typename T>
         169          747483 : inline Anchor<T>::~Anchor()
         170                 : {
         171                 :     /*
         172                 :      * No code is generated for this. But because this is marked 'volatile', G++ will
         173                 :      * assume it has important side-effects, and won't delete it. (G++ never looks at
         174                 :      * the actual text and notices it's empty.) And because we have passed |hold| to
         175                 :      * it, GCC will keep |hold| alive until this point.
         176                 :      *
         177                 :      * The "memory" clobber operand ensures that G++ will not move prior memory
         178                 :      * accesses after the asm --- it's a barrier. Unfortunately, it also means that
         179                 :      * G++ will assume that all memory has changed after the asm, as it would for a
         180                 :      * call to an unknown function. I don't know of a way to avoid that consequence.
         181                 :      */
         182          747483 :     asm volatile("":: "g" (hold) : "memory");
         183          747483 : }
         184                 : #else
         185                 : template<typename T>
         186                 : inline Anchor<T>::~Anchor()
         187                 : {
         188                 :     /*
         189                 :      * An adequate portable substitute, for non-structure types.
         190                 :      *
         191                 :      * The compiler promises that, by the end of an expression statement, the
         192                 :      * last-stored value to a volatile object is the same as it would be in an
         193                 :      * unoptimized, direct implementation (the "abstract machine" whose behavior the
         194                 :      * language spec describes). However, the compiler is still free to reorder
         195                 :      * non-volatile accesses across this store --- which is what we must prevent. So
         196                 :      * assigning the held value to a volatile variable, as we do here, is not enough.
         197                 :      *
         198                 :      * In our case, however, garbage collection only occurs at function calls, so it
         199                 :      * is sufficient to ensure that the destructor's store isn't moved earlier across
         200                 :      * any function calls that could collect. It is hard to imagine the compiler
         201                 :      * analyzing the program so thoroughly that it could prove that such motion was
         202                 :      * safe. In practice, compilers treat calls to the collector as opaque operations
         203                 :      * --- in particular, as operations which could access volatile variables, across
         204                 :      * which this destructor must not be moved.
         205                 :      *
         206                 :      * ("Objection, your honor!  *Alleged* killer whale!")
         207                 :      *
         208                 :      * The disadvantage of this approach is that it does generate code for the store.
         209                 :      * We do need to use Anchors in some cases where cycles are tight.
         210                 :      *
         211                 :      * NB: there is a Anchor<Value>::~Anchor() specialization below.
         212                 :      */
         213                 :     volatile T sink;
         214                 :     sink = hold;
         215                 : }
         216                 : #endif  /* defined(__GNUC__) */
         217                 :
         218                 : /*
         219                 :  * Methods for poisoning GC heap pointer words and checking for poisoned words.
         220                 :  * These are in this file for use in Value methods and so forth.
         221                 :  *
         222                 :  * If the moving GC hazard analysis is in use and detects a non-rooted stack
         223                 :  * pointer to a GC thing, one byte of that pointer is poisoned to refer to an
         224                 :  * invalid location. For both 32 bit and 64 bit systems, the fourth byte of the
         225                 :  * pointer is overwritten, to reduce the likelihood of accidentally changing
         226                 :  * a live integer value.
         227                 :  */
         228                 :
         229                 : inline void PoisonPtr(uintptr_t *v)
         230                 : {
         231                 : #if defined(JSGC_ROOT_ANALYSIS) && defined(DEBUG)
         232                 :     uint8_t *ptr = (uint8_t *) v + 3;
         233                 :     *ptr = JS_FREE_PATTERN;
         234                 : #endif
         235                 : }
         236                 :
         237                 : template <typename T>
         238       962525200 : inline bool IsPoisonedPtr(T *v)
         239                 : {
         240                 : #if defined(JSGC_ROOT_ANALYSIS) && defined(DEBUG)
         241                 :     uint32_t mask = uintptr_t(v) & 0xff000000;
         242                 :     return mask == uint32_t(JS_FREE_PATTERN << 24);
         243                 : #else
         244       962525200 :     return false;
         245                 : #endif
         246                 : }
         247                 :
         248                 : /*
         249                 :  * JS::Value is the C++ interface for a single JavaScript Engine value.
         250                 :  * A few general notes on JS::Value:
         251                 :  *
         252                 :  * - JS::Value has setX() and isX() members for X in
         253                 :  *
         254                 :  *     { Int32, Double, String, Boolean, Undefined, Null, Object, Magic }
         255                 :  *
         256                 :  *   JS::Value also contains toX() for each of the non-singleton types.
         257                 :  *
         258                 :  * - Magic is a singleton type whose payload contains a JSWhyMagic "reason" for
         259                 :  *   the magic value. By providing JSWhyMagic values when creating and checking
         260                 :  *   for magic values, it is possible to assert, at runtime, that only magic
         261                 :  *   values with the expected reason flow through a particular value. For
         262                 :  *   example, if cx->exception has a magic value, the reason must be
         263                 :  *   JS_GENERATOR_CLOSING.
         264                 :  *
         265                 :  * - A key difference between JSVAL_* and JS::Value operations is that
         266                 :  *   JS::Value gives null a separate type. Thus
         267                 :  *
         268                 :  *           JSVAL_IS_OBJECT(v) === v.isObjectOrNull()
         269                 :  *       !JSVAL_IS_PRIMITIVE(v) === v.isObject()
         270                 :  *
         271                 :  *   To help prevent mistakenly boxing a nullable JSObject* as an object,
         272                 :  *   Value::setObject takes a JSObject&. (Conversely, Value::asObject returns a
         273                 :  *   JSObject&. A convenience member Value::setObjectOrNull is provided.
         274                 :  *
         275                 :  * - JSVAL_VOID is the same as the singleton value of the Undefined type.
         276                 :  *
         277                 :  * - Note that JS::Value is 8 bytes on 32 and 64-bit architectures. Thus, on
         278                 :  *   32-bit user code should avoid copying jsval/JS::Value as much as possible,
         279                 :  *   preferring to pass by const Value &.
         280                 :  */
         281                 : class Value
         282       167142985 : {
         283                 :   public:
         284                 :     /*
         285                 :      * N.B. the default constructor leaves Value unitialized. Adding a default
         286                 :      * constructor prevents Value from being stored in a union.
         287                 :      */
         288                 :
         289                 :     /*** Mutators ***/
         290                 :
         291                 :     JS_ALWAYS_INLINE
         292        25289897 :     void setNull() {
         293        25289897 :         data.asBits = BUILD_JSVAL(JSVAL_TAG_NULL, 0).asBits;
         294        25289897 :     }
         295                 :
         296                 :     JS_ALWAYS_INLINE
         297       142849138 :     void setUndefined() {
         298       142849138 :         data.asBits = BUILD_JSVAL(JSVAL_TAG_UNDEFINED, 0).asBits;
         299       142849138 :     }
         300                 :
         301                 :     JS_ALWAYS_INLINE
         302       680919235 :     void setInt32(int32_t i) {
         303       680919235 :         data = INT32_TO_JSVAL_IMPL(i);
         304       680919235 :     }
         305                 :
         306                 :     JS_ALWAYS_INLINE
         307                 :     int32_t &getInt32Ref() {
         308                 :         JS_ASSERT(isInt32());
         309                 :         return data.s.payload.i32;
         310                 :     }
         311                 :
         312                 :     JS_ALWAYS_INLINE
         313        17662549 :     void setDouble(double d) {
         314        17662549 :         data = DOUBLE_TO_JSVAL_IMPL(d);
         315        17662549 :     }
         316                 :
         317                 :     JS_ALWAYS_INLINE
         318            1146 :     double &getDoubleRef() {
         319            1146 :         JS_ASSERT(isDouble());
         320            1146 :         return data.asDouble;
         321                 :     }
         322                 :
         323                 :     JS_ALWAYS_INLINE
         324       119387220 :     void setString(JSString *str) {
         325       119387220 :         JS_ASSERT(!IsPoisonedPtr(str));
         326       119387220 :         data = STRING_TO_JSVAL_IMPL(str);
         327       119387220 :     }
         328                 :
         329                 :     JS_ALWAYS_INLINE
         330                 :     void setString(const JS::Anchor<JSString *> &str) {
         331                 :         setString(str.get());
         332                 :     }
         333                 :
         334                 :     JS_ALWAYS_INLINE
         335       107452235 :     void setObject(JSObject &obj) {
         336       107452235 :         JS_ASSERT(!IsPoisonedPtr(&obj));
         337       107452235 :         data = OBJECT_TO_JSVAL_IMPL(&obj);
         338       107452235 :     }
         339                 :
         340                 :     JS_ALWAYS_INLINE
         341        32118119 :     void setBoolean(bool b) {
         342        32118119 :         data = BOOLEAN_TO_JSVAL_IMPL(b);
         343        32118119 :     }
         344                 :
         345                 :     JS_ALWAYS_INLINE
         346        26795126 :     void setMagic(JSWhyMagic why) {
         347        26795126 :         data = MAGIC_TO_JSVAL_IMPL(why);
         348        26795126 :     }
         349                 :
         350                 :     JS_ALWAYS_INLINE
         351         5410447 :     bool setNumber(uint32_t ui) {
         352         5410447 :         if (ui > JSVAL_INT_MAX) {
         353             909 :             setDouble((double)ui);
         354             909 :             return false;
         355                 :         } else {
         356         5409538 :             setInt32((int32_t)ui);
         357         5409538 :             return true;
         358                 :         }
         359                 :     }
         360                 :
         361                 :     JS_ALWAYS_INLINE
         362        62131891 :     bool setNumber(double d) {
         363                 :         int32_t i;
         364        62131891 :         if (JSDOUBLE_IS_INT32(d, &i)) {
         365        49147998 :             setInt32(i);
         366        49147998 :             return true;
         367                 :         } else {
         368        12983893 :             setDouble(d);
         369        12983893 :             return false;
         370                 :         }
         371                 :     }
         372                 :
         373                 :     JS_ALWAYS_INLINE
         374         6354123 :     void setObjectOrNull(JSObject *arg) {
         375         6354123 :         if (arg)
         376         6143038 :             setObject(*arg);
         377                 :         else
         378          211085 :             setNull();
         379         6354123 :     }
         380                 :
         381                 :     JS_ALWAYS_INLINE
         382         7035032 :     void swap(Value &rhs) {
         383         7035032 :         uint64_t tmp = rhs.data.asBits;
         384         7035032 :         rhs.data.asBits = data.asBits;
         385         7035032 :         data.asBits = tmp;
         386         7035032 :     }
         387                 :
         388                 :     /*** Value type queries ***/
         389                 :
         390                 :     JS_ALWAYS_INLINE
         391        42465953 :     bool isUndefined() const {
         392        42465953 :         return JSVAL_IS_UNDEFINED_IMPL(data);
         393                 :     }
         394                 :
         395                 :     JS_ALWAYS_INLINE
         396        62569501 :     bool isNull() const {
         397        62569501 :         return JSVAL_IS_NULL_IMPL(data);
         398                 :     }
         399                 :
         400                 :     JS_ALWAYS_INLINE
         401         3484228 :     bool isNullOrUndefined() const {
         402         3484228 :         return isNull() || isUndefined();
         403                 :     }
         404                 :
         405                 :     JS_ALWAYS_INLINE
         406      1966051316 :     bool isInt32() const {
         407      1966051316 :         return JSVAL_IS_INT32_IMPL(data);
         408                 :     }
         409                 :
         410                 :     JS_ALWAYS_INLINE
         411             306 :     bool isInt32(int32_t i32) const {
         412             306 :         return JSVAL_IS_SPECIFIC_INT32_IMPL(data, i32);
         413                 :     }
         414                 :
         415                 :     JS_ALWAYS_INLINE
         416       378745764 :     bool isDouble() const {
         417       378745764 :         return JSVAL_IS_DOUBLE_IMPL(data);
         418                 :     }
         419                 :
         420                 :     JS_ALWAYS_INLINE
         421       183677422 :     bool isNumber() const {
         422       183677422 :         return JSVAL_IS_NUMBER_IMPL(data);
         423                 :     }
         424                 :
         425                 :     JS_ALWAYS_INLINE
         426      1338160190 :     bool isString() const {
         427      1338160190 :         return JSVAL_IS_STRING_IMPL(data);
         428                 :     }
         429                 :
         430                 :     JS_ALWAYS_INLINE
         431     -2006412904 :     bool isObject() const {
         432     -2006412904 :         return JSVAL_IS_OBJECT_IMPL(data);
         433                 :     }
         434                 :
         435                 :     JS_ALWAYS_INLINE
         436        54306063 :     bool isPrimitive() const {
         437        54306063 :         return JSVAL_IS_PRIMITIVE_IMPL(data);
         438                 :     }
         439                 :
         440                 :     JS_ALWAYS_INLINE
         441         3616025 :     bool isObjectOrNull() const {
         442         3616025 :         return JSVAL_IS_OBJECT_OR_NULL_IMPL(data);
         443                 :     }
         444                 :
         445                 :     JS_ALWAYS_INLINE
         446        21042772 :     bool isGCThing() const {
         447        21042772 :         return JSVAL_IS_GCTHING_IMPL(data);
         448                 :     }
         449                 :
         450                 :     JS_ALWAYS_INLINE
         451        40957325 :     bool isBoolean() const {
         452        40957325 :         return JSVAL_IS_BOOLEAN_IMPL(data);
         453                 :     }
         454                 :
         455                 :     JS_ALWAYS_INLINE
         456        44170516 :     bool isTrue() const {
         457        44170516 :         return JSVAL_IS_SPECIFIC_BOOLEAN(data, true);
         458                 :     }
         459                 :
         460                 :     JS_ALWAYS_INLINE
         461          111812 :     bool isFalse() const {
         462          111812 :         return JSVAL_IS_SPECIFIC_BOOLEAN(data, false);
         463                 :     }
         464                 :
         465                 :     JS_ALWAYS_INLINE
         466       180594192 :     bool isMagic() const {
         467       180594192 :         return JSVAL_IS_MAGIC_IMPL(data);
         468                 :     }
         469                 :
         470                 :     JS_ALWAYS_INLINE
         471       131973012 :     bool isMagic(JSWhyMagic why) const {
         472       131973012 :         JS_ASSERT_IF(isMagic(), data.s.payload.why == why);
         473       131973012 :         return JSVAL_IS_MAGIC_IMPL(data);
         474                 :     }
         475                 :
         476                 :     JS_ALWAYS_INLINE
         477       131789308 :     bool isMarkable() const {
         478       131789308 :         return JSVAL_IS_TRACEABLE_IMPL(data);
         479                 :     }
         480                 :
         481                 :     JS_ALWAYS_INLINE
         482         6957567 :     JSGCTraceKind gcKind() const {
         483         6957567 :         JS_ASSERT(isMarkable());
         484         6957567 :         return JSGCTraceKind(JSVAL_TRACE_KIND_IMPL(data));
         485                 :     }
         486                 :
         487                 :     JS_ALWAYS_INLINE
         488            2016 :     JSWhyMagic whyMagic() const {
         489            2016 :         JS_ASSERT(isMagic());
         490            2016 :         return data.s.payload.why;
         491                 :     }
         492                 :
         493                 :     /*** Comparison ***/
         494                 :
         495                 :     JS_ALWAYS_INLINE
         496         2605810 :     bool operator==(const Value &rhs) const {
         497         2605810 :         return data.asBits == rhs.data.asBits;
         498                 :     }
         499                 :
         500                 :     JS_ALWAYS_INLINE
         501         4937027 :     bool operator!=(const Value &rhs) const {
         502         4937027 :         return data.asBits != rhs.data.asBits;
         503                 :     }
         504                 :
         505                 :     friend inline bool SameType(const Value &lhs, const Value &rhs);
         506                 :
         507                 :     /*** Extract the value's typed payload ***/
         508                 :
         509                 :     JS_ALWAYS_INLINE
         510      1051521160 :     int32_t toInt32() const {
         511      1051521160 :         JS_ASSERT(isInt32());
         512      1051521160 :         return JSVAL_TO_INT32_IMPL(data);
         513                 :     }
         514                 :
         515                 :     JS_ALWAYS_INLINE
         516        35360212 :     double toDouble() const {
         517        35360212 :         JS_ASSERT(isDouble());
         518        35360212 :         return data.asDouble;
         519                 :     }
         520                 :
         521                 :     JS_ALWAYS_INLINE
         522        87404853 :     double toNumber() const {
         523        87404853 :         JS_ASSERT(isNumber());
         524        87404853 :         return isDouble() ? toDouble() : double(toInt32());
         525                 :     }
         526                 :
         527                 :     JS_ALWAYS_INLINE
         528       152065704 :     JSString *toString() const {
         529       152065704 :         JS_ASSERT(isString());
         530       152065704 :         return JSVAL_TO_STRING_IMPL(data);
         531                 :     }
         532                 :
         533                 :     JS_ALWAYS_INLINE
         534       637500441 :     JSObject &toObject() const {
         535       637500441 :         JS_ASSERT(isObject());
         536       637500441 :         return *JSVAL_TO_OBJECT_IMPL(data);
         537                 :     }
         538                 :
         539                 :     JS_ALWAYS_INLINE
         540         1210182 :     JSObject *toObjectOrNull() const {
         541         1210182 :         JS_ASSERT(isObjectOrNull());
         542         1210182 :         return JSVAL_TO_OBJECT_IMPL(data);
         543                 :     }
         544                 :
         545                 :     JS_ALWAYS_INLINE
         546        21042772 :     void *toGCThing() const {
         547        21042772 :         JS_ASSERT(isGCThing());
         548        21042772 :         return JSVAL_TO_GCTHING_IMPL(data);
         549                 :     }
         550                 :
         551                 :     JS_ALWAYS_INLINE
         552        22808422 :     bool toBoolean() const {
         553        22808422 :         JS_ASSERT(isBoolean());
         554        22808422 :         return JSVAL_TO_BOOLEAN_IMPL(data);
         555                 :     }
         556                 :
         557                 :     JS_ALWAYS_INLINE
         558        17454624 :     uint32_t payloadAsRawUint32() const {
         559        17454624 :         JS_ASSERT(!isDouble());
         560        17454624 :         return data.s.payload.u32;
         561                 :     }
         562                 :
         563                 :     JS_ALWAYS_INLINE
         564         4733145 :     uint64_t asRawBits() const {
         565         4733145 :         return data.asBits;
         566                 :     }
         567                 :
         568                 :     JS_ALWAYS_INLINE
         569       116057337 :     JSValueType extractNonDoubleType() const {
         570       116057337 :         return JSVAL_EXTRACT_NON_DOUBLE_TYPE_IMPL(data);
         571                 :     }
         572                 :
         573                 :     /*
         574                 :      * Private API
         575                 :      *
         576                 :      * Private setters/getters allow the caller to read/write arbitrary types
         577                 :      * that fit in the 64-bit payload. It is the caller's responsibility, after
         578                 :      * storing to a value with setPrivateX to read only using getPrivateX.
         579                 :      * Privates values are given a type type which ensures they are not marked.
         580                 :      */
         581                 :
         582                 :     JS_ALWAYS_INLINE
         583         2556483 :     void setPrivate(void *ptr) {
         584         2556483 :         data = PRIVATE_PTR_TO_JSVAL_IMPL(ptr);
         585         2556483 :     }
         586                 :
         587                 :     JS_ALWAYS_INLINE
         588         3979268 :     void *toPrivate() const {
         589         3979268 :         JS_ASSERT(JSVAL_IS_DOUBLE_IMPL(data));
         590         3979268 :         return JSVAL_TO_PRIVATE_PTR_IMPL(data);
         591                 :     }
         592                 :
         593                 :     JS_ALWAYS_INLINE
         594          108780 :     void setPrivateUint32(uint32_t ui) {
         595          108780 :         data = PRIVATE_UINT32_TO_JSVAL_IMPL(ui);
         596          108780 :     }
         597                 :
         598                 :     JS_ALWAYS_INLINE
         599          180092 :     uint32_t toPrivateUint32() const {
         600          180092 :         JS_ASSERT(JSVAL_IS_DOUBLE_IMPL(data));
         601          180092 :         return JSVAL_TO_PRIVATE_UINT32_IMPL(data);
         602                 :     }
         603                 :
         604                 :     JS_ALWAYS_INLINE
         605                 :     uint32_t &getPrivateUint32Ref() {
         606                 :         JS_ASSERT(isDouble());
         607                 :         return data.s.payload.u32;
         608                 :     }
         609                 :
         610                 :     /*
         611                 :      * An unmarked value is just a void* cast as a Value. Thus, the Value is
         612                 :      * not safe for GC and must not be marked. This API avoids raw casts
         613                 :      * and the ensuing strict-aliasing warnings.
         614                 :      */
         615                 :
         616                 :     JS_ALWAYS_INLINE
         617                 :     void setUnmarkedPtr(void *ptr) {
         618                 :         data.asPtr = ptr;
         619                 :     }
         620                 :
         621                 :     JS_ALWAYS_INLINE
         622                 :     void *toUnmarkedPtr() const {
         623                 :         return data.asPtr;
         624                 :     }
         625                 :
         626               0 :     const size_t *payloadWord() const {
         627                 : #if JS_BITS_PER_WORD == 32
         628               0 :         return &data.s.payload.word;
         629                 : #elif JS_BITS_PER_WORD == 64
         630                 :         return &data.asWord;
         631                 : #endif
         632                 :     }
         633                 :
         634                 : #if !defined(_MSC_VER) && !defined(__sparc)
         635                 :   /* To make jsval binary compatible when linking across C and C++ with MSVC,
         636                 :    * JS::Value needs to be POD. Otherwise, jsval will be passed in memory
         637                 :    * in C++ but by value in C (bug 645111).
         638                 :    * Same issue for SPARC ABI. (bug 737344).
         639                 :    */
         640                 :   private:
         641                 : #endif
         642                 :
         643                 :     jsval_layout data;
         644                 :
         645                 :   private:
         646                 :     void staticAssertions() {
         647                 :         JS_STATIC_ASSERT(sizeof(JSValueType) == 1);
         648                 :         JS_STATIC_ASSERT(sizeof(JSValueTag) == 4);
         649                 :         JS_STATIC_ASSERT(sizeof(JSBool) == 4);
         650                 :         JS_STATIC_ASSERT(sizeof(JSWhyMagic) <= 4);
         651                 :         JS_STATIC_ASSERT(sizeof(Value) == 8);
         652                 :     }
         653                 :
         654                 :     friend jsval_layout (::JSVAL_TO_IMPL)(Value);
         655                 :     friend Value (::IMPL_TO_JSVAL)(jsval_layout l);
         656                 : };
         657                 :
         658                 : inline bool
         659       182381775 : IsPoisonedValue(const Value &v)
         660                 : {
         661       182381775 :     if (v.isString())
         662        33806503 :         return IsPoisonedPtr(v.toString());
         663       148575272 :     if (v.isObject())
         664        33131974 :         return IsPoisonedPtr(&v.toObject());
         665       115443298 :     return false;
         666                 : }
         667                 :
         668                 : /************************************************************************/
         669                 :
         670                 : static JS_ALWAYS_INLINE Value
         671         6656208 : NullValue()
         672                 : {
         673                 :     Value v;
         674         6656208 :     v.setNull();
         675                 :     return v;
         676                 : }
         677                 :
         678                 : static JS_ALWAYS_INLINE Value
         679        98197624 : UndefinedValue()
         680                 : {
         681                 :     Value v;
         682        98197624 :     v.setUndefined();
         683                 :     return v;
         684                 : }
         685                 :
         686                 : static JS_ALWAYS_INLINE Value
         687       403918805 : Int32Value(int32_t i32)
         688                 : {
         689                 :     Value v;
         690       403918805 :     v.setInt32(i32);
         691                 :     return v;
         692                 : }
         693                 :
         694                 : static JS_ALWAYS_INLINE Value
         695          144722 : DoubleValue(double dbl)
         696                 : {
         697                 :     Value v;
         698          144722 :     v.setDouble(dbl);
         699                 :     return v;
         700                 : }
         701                 :
         702                 : static JS_ALWAYS_INLINE Value
         703        86942199 : StringValue(JSString *str)
         704                 : {
         705                 :     Value v;
         706        86942199 :     v.setString(str);
         707                 :     return v;
         708                 : }
         709                 :
         710                 : static JS_ALWAYS_INLINE Value
         711         2955116 : BooleanValue(bool boo)
         712                 : {
         713                 :     Value v;
         714         2955116 :     v.setBoolean(boo);
         715                 :     return v;
         716                 : }
         717                 :
         718                 : static JS_ALWAYS_INLINE Value
         719        12845524 : ObjectValue(JSObject &obj)
         720                 : {
         721                 :     Value v;
         722        12845524 :     v.setObject(obj);
         723                 :     return v;
         724                 : }
         725                 :
         726                 : static JS_ALWAYS_INLINE Value
         727        13923979 : MagicValue(JSWhyMagic why)
         728                 : {
         729                 :     Value v;
         730        13923979 :     v.setMagic(why);
         731                 :     return v;
         732                 : }
         733                 :
         734                 : static JS_ALWAYS_INLINE Value
         735        22325752 : NumberValue(double dbl)
         736                 : {
         737                 :     Value v;
         738        22325752 :     v.setNumber(dbl);
         739                 :     return v;
         740                 : }
         741                 :
         742                 : static JS_ALWAYS_INLINE Value
         743          967278 : ObjectOrNullValue(JSObject *obj)
         744                 : {
         745                 :     Value v;
         746          967278 :     v.setObjectOrNull(obj);
         747                 :     return v;
         748                 : }
         749                 :
         750                 : static JS_ALWAYS_INLINE Value
         751         2556393 : PrivateValue(void *ptr)
         752                 : {
         753                 :     Value v;
         754         2556393 :     v.setPrivate(ptr);
         755                 :     return v;
         756                 : }
         757                 :
         758                 : static JS_ALWAYS_INLINE Value
         759          108780 : PrivateUint32Value(uint32_t ui)
         760                 : {
         761                 :     Value v;
         762          108780 :     v.setPrivateUint32(ui);
         763                 :     return v;
         764                 : }
         765                 :
         766                 : JS_ALWAYS_INLINE bool
         767        14958488 : SameType(const Value &lhs, const Value &rhs)
         768                 : {
         769        14958488 :     return JSVAL_SAME_TYPE_IMPL(lhs.data, rhs.data);
         770                 : }
         771                 :
         772                 : /************************************************************************/
         773                 :
         774                 : #ifndef __GNUC__
         775                 :
         776                 : /*
         777                 :  * The default assignment operator for |struct C| has the signature:
         778                 :  *
         779                 :  *   C& C::operator=(const C&)
         780                 :  *
         781                 :  * And in particular requires implicit conversion of |this| to type |C| for the
         782                 :  * return value. But |volatile C| cannot thus be converted to |C|, so just
         783                 :  * doing |sink = hold| as in the non-specialized version would fail to compile.
         784                 :  * Do the assignment on asBits instead, since I don't think we want to give
         785                 :  * jsval_layout an assignment operator returning |volatile jsval_layout|.
         786                 :  */
         787                 : template<>
         788                 : inline Anchor<Value>::~Anchor()
         789                 : {
         790                 :     volatile uint64_t bits;
         791                 :     bits = JSVAL_TO_IMPL(hold).asBits;
         792                 : }
         793                 :
         794                 : #endif
         795                 :
         796                 : #if defined JS_THREADSAFE && defined DEBUG
         797                 :
         798                 : class JS_PUBLIC_API(AutoCheckRequestDepth)
         799                 : {
         800                 :     JSContext *cx;
         801                 :   public:
         802                 :     AutoCheckRequestDepth(JSContext *cx);
         803                 :     ~AutoCheckRequestDepth();
         804                 : };
         805                 :
         806                 : # define CHECK_REQUEST(cx) \
         807                 :     JS::AutoCheckRequestDepth _autoCheckRequestDepth(cx)
         808                 :
         809                 : #else
         810                 :
         811                 : # define CHECK_REQUEST(cx) \
         812                 :     ((void) 0)
         813                 :
         814                 : #endif /* JS_THREADSAFE && DEBUG */
         815                 :
         816                 : #ifdef DEBUG
         817                 : /* Assert that we're not doing GC on cx, that we're in a request as
         818                 :    needed, and that the compartments for cx and v are correct. */
         819                 : JS_PUBLIC_API(void)
         820                 : AssertArgumentsAreSane(JSContext *cx, const Value &v);
         821                 : #else
         822                 : inline void AssertArgumentsAreSane(JSContext *cx, const Value &v) {
         823                 :     /* Do nothing */
         824                 : }
         825                 : #endif /* DEBUG */
         826                 :
         827                 : class JS_PUBLIC_API(AutoGCRooter) {
         828                 :   public:
         829                 :     AutoGCRooter(JSContext *cx, ptrdiff_t tag);
         830                 :
         831        16498149 :     ~AutoGCRooter() {
         832        16498149 :         JS_ASSERT(this == *stackTop);
         833        16498149 :         *stackTop = down;
         834        16498149 :     }
         835                 :
         836                 :     /* Implemented in jsgc.cpp. */
         837                 :     inline void trace(JSTracer *trc);
         838                 :     static void traceAll(JSTracer *trc);
         839                 :
         840                 :   protected:
         841                 :     AutoGCRooter * const down;
         842                 :
         843                 :     /*
         844                 :      * Discriminates actual subclass of this being used.  If non-negative, the
         845                 :      * subclass roots an array of values of the length stored in this field.
         846                 :      * If negative, meaning is indicated by the corresponding value in the enum
         847                 :      * below.  Any other negative value indicates some deeper problem such as
         848                 :      * memory corruption.
         849                 :      */
         850                 :     ptrdiff_t tag;
         851                 :
         852                 :     enum {
         853                 :         JSVAL =        -1, /* js::AutoValueRooter */
         854                 :         VALARRAY =     -2, /* js::AutoValueArrayRooter */
         855                 :         PARSER =       -3, /* js::Parser */
         856                 :         SHAPEVECTOR =  -4, /* js::AutoShapeVector */
         857                 :         ENUMERATOR =   -5, /* js::AutoEnumStateRooter */
         858                 :         IDARRAY =      -6, /* js::AutoIdArray */
         859                 :         DESCRIPTORS =  -7, /* js::AutoPropDescArrayRooter */
         860                 :         NAMESPACES =   -8, /* js::AutoNamespaceArray */
         861                 :         XML =          -9, /* js::AutoXMLRooter */
         862                 :         OBJECT =      -10, /* js::AutoObjectRooter */
         863                 :         ID =          -11, /* js::AutoIdRooter */
         864                 :         VALVECTOR =   -12, /* js::AutoValueVector */
         865                 :         DESCRIPTOR =  -13, /* js::AutoPropertyDescriptorRooter */
         866                 :         STRING =      -14, /* js::AutoStringRooter */
         867                 :         IDVECTOR =    -15, /* js::AutoIdVector */
         868                 :         OBJVECTOR =   -16, /* js::AutoObjectVector */
         869                 :         SCRIPTVECTOR =-17  /* js::AutoScriptVector */
         870                 :     };
         871                 :
         872                 :   private:
         873                 :     AutoGCRooter ** const stackTop;
         874                 :
         875                 :     /* No copy or assignment semantics. */
         876                 :     AutoGCRooter(AutoGCRooter &ida) MOZ_DELETE;
         877                 :     void operator=(AutoGCRooter &ida) MOZ_DELETE;
         878                 : };
         879                 :
         880                 : class AutoValueRooter : private AutoGCRooter
         881         1026643 : {
         882                 :   public:
         883          106252 :     explicit AutoValueRooter(JSContext *cx
         884                 :                              JS_GUARD_OBJECT_NOTIFIER_PARAM)
         885          106252 :       : AutoGCRooter(cx, JSVAL), val(NullValue())
         886                 :     {
         887          106252 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
         888          106252 :     }
         889                 :
         890          920391 :     AutoValueRooter(JSContext *cx, const Value &v
         891                 :                     JS_GUARD_OBJECT_NOTIFIER_PARAM)
         892          920391 :       : AutoGCRooter(cx, JSVAL), val(v)
         893                 :     {
         894          920391 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
         895          920391 :     }
         896                 :
         897                 :     /*
         898                 :      * If you are looking for Object* overloads, use AutoObjectRooter instead;
         899                 :      * rooting Object*s as a js::Value requires discerning whether or not it is
         900                 :      * a function object. Also, AutoObjectRooter is smaller.
         901                 :      */
         902                 :
         903            3672 :     void set(Value v) {
         904            3672 :         JS_ASSERT(tag == JSVAL);
         905            3672 :         val = v;
         906            3672 :     }
         907                 :
         908         1103622 :     const Value &value() const {
         909         1103622 :         JS_ASSERT(tag == JSVAL);
         910         1103622 :         return val;
         911                 :     }
         912                 :
         913          900349 :     Value *addr() {
         914          900349 :         JS_ASSERT(tag == JSVAL);
         915          900349 :         return &val;
         916                 :     }
         917                 :
         918               0 :     const Value &jsval_value() const {
         919               0 :         JS_ASSERT(tag == JSVAL);
         920               0 :         return val;
         921                 :     }
         922                 :
         923             225 :     Value *jsval_addr() {
         924             225 :         JS_ASSERT(tag == JSVAL);
         925             225 :         return &val;
         926                 :     }
         927                 :
         928                 :     friend void AutoGCRooter::trace(JSTracer *trc);
         929                 :
         930                 :   private:
         931                 :     Value val;
         932                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
         933                 : };
         934                 :
         935         1637480 : class AutoObjectRooter : private AutoGCRooter {
         936                 :   public:
         937         1637480 :     AutoObjectRooter(JSContext *cx, JSObject *obj = NULL
         938                 :                      JS_GUARD_OBJECT_NOTIFIER_PARAM)
         939         1637480 :       : AutoGCRooter(cx, OBJECT), obj(obj)
         940                 :     {
         941         1637480 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
         942         1637480 :     }
         943                 :
         944               0 :     void setObject(JSObject *obj) {
         945               0 :         this->obj = obj;
         946               0 :     }
         947                 :
         948                 :     JSObject * object() const {
         949                 :         return obj;
         950                 :     }
         951                 :
         952                 :     JSObject ** addr() {
         953                 :         return &obj;
         954                 :     }
         955                 :
         956                 :     friend void AutoGCRooter::trace(JSTracer *trc);
         957                 :
         958                 :   private:
         959                 :     JSObject *obj;
         960                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
         961                 : };
         962                 :
         963         9661256 : class AutoStringRooter : private AutoGCRooter {
         964                 :   public:
         965         9661256 :     AutoStringRooter(JSContext *cx, JSString *str = NULL
         966                 :                      JS_GUARD_OBJECT_NOTIFIER_PARAM)
         967         9661256 :       : AutoGCRooter(cx, STRING), str(str)
         968                 :     {
         969         9661256 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
         970         9661256 :     }
         971                 :
         972         8961416 :     void setString(JSString *str) {
         973         8961416 :         this->str = str;
         974         8961416 :     }
         975                 :
         976         9705575 :     JSString * string() const {
         977         9705575 :         return str;
         978                 :     }
         979                 :
         980                 :     JSString ** addr() {
         981                 :         return &str;
         982                 :     }
         983                 :
         984                 :     friend void AutoGCRooter::trace(JSTracer *trc);
         985                 :
         986                 :   private:
         987                 :     JSString *str;
         988                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
         989                 : };
         990                 :
         991           32013 : class AutoArrayRooter : private AutoGCRooter {
         992                 :   public:
         993           32013 :     AutoArrayRooter(JSContext *cx, size_t len, Value *vec
         994                 :                     JS_GUARD_OBJECT_NOTIFIER_PARAM)
         995           32013 :       : AutoGCRooter(cx, len), array(vec)
         996                 :     {
         997           32013 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
         998           32013 :         JS_ASSERT(tag >= 0);
         999           32013 :     }
        1000                 :
        1001         2576340 :     void changeLength(size_t newLength) {
        1002         2576340 :         tag = ptrdiff_t(newLength);
        1003         2576340 :         JS_ASSERT(tag >= 0);
        1004         2576340 :     }
        1005                 :
        1006         2576340 :     void changeArray(Value *newArray, size_t newLength) {
        1007         2576340 :         changeLength(newLength);
        1008         2576340 :         array = newArray;
        1009         2576340 :     }
        1010                 :
        1011                 :     Value *array;
        1012                 :
        1013                 :     friend void AutoGCRooter::trace(JSTracer *trc);
        1014                 :
        1015                 :   private:
        1016                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        1017                 : };
        1018                 :
        1019                 : /* The auto-root for enumeration object and its state. */
        1020                 : class AutoEnumStateRooter : private AutoGCRooter
        1021                 : {
        1022                 :   public:
        1023                 :     AutoEnumStateRooter(JSContext *cx, JSObject *obj
        1024                 :                         JS_GUARD_OBJECT_NOTIFIER_PARAM)
        1025                 :       : AutoGCRooter(cx, ENUMERATOR), obj(obj), stateValue(), context(cx)
        1026                 :     {
        1027                 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        1028                 :         JS_ASSERT(obj);
        1029                 :     }
        1030                 :
        1031                 :     ~AutoEnumStateRooter();
        1032                 :
        1033                 :     friend void AutoGCRooter::trace(JSTracer *trc);
        1034                 :
        1035                 :     const Value &state() const { return stateValue; }
        1036                 :     Value *addr() { return &stateValue; }
        1037                 :
        1038                 :   protected:
        1039                 :     void trace(JSTracer *trc);
        1040                 :
        1041                 :     JSObject *obj;
        1042                 :
        1043                 :   private:
        1044                 :     Value stateValue;
        1045                 :     JSContext *context;
        1046                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        1047                 : };
        1048                 :
        1049                 : template<class T>
        1050                 : class AutoVectorRooter : protected AutoGCRooter
        1051         3480379 : {
        1052                 :   public:
        1053         3480379 :     explicit AutoVectorRooter(JSContext *cx, ptrdiff_t tag
        1054                 :                               JS_GUARD_OBJECT_NOTIFIER_PARAM)
        1055         3480379 :         : AutoGCRooter(cx, tag), vector(cx)
        1056                 :     {
        1057         3480379 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        1058         3480379 :     }
        1059                 :
        1060        13144976 :     size_t length() const { return vector.length(); }
        1061                 :
        1062       120239288 :     bool append(const T &v) { return vector.append(v); }
        1063                 :
        1064                 :     /* For use when space has already been reserved. */
        1065          120152 :     void infallibleAppend(const T &v) { vector.infallibleAppend(v); }
        1066                 :
        1067               0 :     void popBack() { vector.popBack(); }
        1068          115819 :     T popCopy() { return vector.popCopy(); }
        1069                 :
        1070            2818 :     bool growBy(size_t inc) {
        1071            2818 :         size_t oldLength = vector.length();
        1072            2818 :         if (!vector.growByUninitialized(inc))
        1073               0 :             return false;
        1074            2818 :         makeRangeGCSafe(oldLength);
        1075            2818 :         return true;
        1076                 :     }
        1077                 :
        1078           33435 :     bool resize(size_t newLength) {
        1079           33435 :         size_t oldLength = vector.length();
        1080           33435 :         if (newLength <= oldLength) {
        1081             144 :             vector.shrinkBy(oldLength - newLength);
        1082             144 :             return true;
        1083                 :         }
        1084           33291 :         if (!vector.growByUninitialized(newLength - oldLength))
        1085               0 :             return false;
        1086           33291 :         makeRangeGCSafe(oldLength);
        1087           33291 :         return true;
        1088                 :     }
        1089                 :
        1090               9 :     void clear() { vector.clear(); }
        1091                 :
        1092           44461 :     bool reserve(size_t newLength) {
        1093           44461 :         return vector.reserve(newLength);
        1094                 :     }
        1095                 :
        1096         9672147 :     T &operator[](size_t i) { return vector[i]; }
        1097        53250535 :     const T &operator[](size_t i) const { return vector[i]; }
        1098                 :
        1099                 :     const T *begin() const { return vector.begin(); }
        1100         3516166 :     T *begin() { return vector.begin(); }
        1101                 :
        1102                 :     const T *end() const { return vector.end(); }
        1103         3388534 :     T *end() { return vector.end(); }
        1104                 :
        1105           70709 :     const T &back() const { return vector.back(); }
        1106                 :
        1107                 :     friend void AutoGCRooter::trace(JSTracer *trc);
        1108                 :
        1109                 :   private:
        1110           36109 :     void makeRangeGCSafe(size_t oldLength) {
        1111           36109 :         T *t = vector.begin() + oldLength;
        1112          151275 :         for (size_t i = oldLength; i < vector.length(); ++i, ++t)
        1113          115166 :             memset(t, 0, sizeof(T));
        1114           36109 :     }
        1115                 :
        1116                 :     typedef js::Vector<T, 8> VectorImpl;
        1117                 :     VectorImpl vector;
        1118                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        1119                 : };
        1120                 :
        1121                 : class AutoValueVector : public AutoVectorRooter<Value>
        1122          535431 : {
        1123                 :   public:
        1124          535431 :     explicit AutoValueVector(JSContext *cx
        1125                 :                              JS_GUARD_OBJECT_NOTIFIER_PARAM)
        1126          535431 :         : AutoVectorRooter<Value>(cx, VALVECTOR)
        1127                 :     {
        1128          535431 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        1129          535431 :     }
        1130                 :
        1131                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        1132                 : };
        1133                 :
        1134                 : class AutoIdVector : public AutoVectorRooter<jsid>
        1135         1700911 : {
        1136                 :   public:
        1137         1700911 :     explicit AutoIdVector(JSContext *cx
        1138                 :                           JS_GUARD_OBJECT_NOTIFIER_PARAM)
        1139         1700911 :         : AutoVectorRooter<jsid>(cx, IDVECTOR)
        1140                 :     {
        1141         1700911 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        1142         1700911 :     }
        1143                 :
        1144                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        1145                 : };
        1146                 :
        1147                 : class AutoScriptVector : public AutoVectorRooter<JSScript *>
        1148             882 : {
        1149                 :   public:
        1150             882 :     explicit AutoScriptVector(JSContext *cx
        1151                 :                               JS_GUARD_OBJECT_NOTIFIER_PARAM)
        1152             882 :         : AutoVectorRooter<JSScript *>(cx, SCRIPTVECTOR)
        1153                 :     {
        1154             882 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        1155             882 :     }
        1156                 :
        1157                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        1158                 : };
        1159                 :
        1160                 : }  /* namespace JS */
        1161                 :
        1162                 : /************************************************************************/
        1163                 :
        1164                 : /*
        1165                 :  * JS::Value and jsval are the same type; jsval is the old name, kept around
        1166                 :  * for backwards compatibility along with all the JSVAL_* operations below.
        1167                 :  * jsval_layout is an implementation detail and should not be used externally.
        1168                 :  */
        1169                 : typedef JS::Value jsval;
        1170                 :
        1171                 : static JS_ALWAYS_INLINE jsval_layout
        1172        31521440 : JSVAL_TO_IMPL(jsval v)
        1173                 : {
        1174        31521440 :     return v.data;
        1175                 : }
        1176                 :
        1177                 : static JS_ALWAYS_INLINE jsval
        1178        13258117 : IMPL_TO_JSVAL(jsval_layout l)
        1179                 : {
        1180                 :     JS::Value v;
        1181        13258117 :     v.data = l;
        1182                 :     return v;
        1183                 : }
        1184                 :
        1185                 : #ifdef DEBUG
        1186                 : struct JSValueAlignmentTester { char c; JS::Value v; };
        1187                 : JS_STATIC_ASSERT(sizeof(JSValueAlignmentTester) == 16);
        1188                 : #endif /* DEBUG */
        1189                 :
        1190                 : #else  /* defined(__cplusplus) */
        1191                 :
        1192                 : /*
        1193                 :  * For SpiderMonkey C clients, there is no JS::Value class, only the
        1194                 :  * traditional jsval with the traditional JSVAL_* operations. Since
        1195                 :  * SpiderMonkey itself is always compiled as C++, this relies on the binary
        1196                 :  * compatibility of jsval_layout and JS::Value (statically asserted below).
        1197                 :  */
        1198                 : typedef union jsval_layout jsval;
        1199                 :
        1200                 : static JS_ALWAYS_INLINE jsval_layout
        1201                 : JSVAL_TO_IMPL(jsval v)
        1202                 : {
        1203                 :     return v;
        1204                 : }
        1205                 :
        1206                 : static JS_ALWAYS_INLINE jsval
        1207                 : IMPL_TO_JSVAL(jsval_layout l)
        1208                 : {
        1209                 :     return l;
        1210                 : }
        1211                 :
        1212                 : #endif  /* defined(__cplusplus) */
        1213                 :
        1214                 : #ifdef DEBUG
        1215                 : typedef struct { char c; jsval_layout l; } JSLayoutAlignmentTester;
        1216                 : JS_STATIC_ASSERT(sizeof(JSLayoutAlignmentTester) == 16);
        1217                 : #endif /* DEBUG */
        1218                 :
        1219                 : JS_STATIC_ASSERT(sizeof(jsval_layout) == sizeof(jsval));
        1220                 :
        1221                 : /************************************************************************/
        1222                 :
        1223                 : /* JSClass operation signatures. */
        1224                 :
        1225                 : /*
        1226                 :  * Add, delete, or get a property named by id in obj.  Note the jsid id
        1227                 :  * type -- id may be a string (Unicode property identifier) or an int (element
        1228                 :  * index).  The *vp out parameter, on success, is the new property value after
        1229                 :  * an add or get.  After a successful delete, *vp is JSVAL_FALSE iff
        1230                 :  * obj[id] can't be deleted (because it's permanent).
        1231                 :  */
        1232                 : typedef JSBool
        1233                 : (* JSPropertyOp)(JSContext *cx, JSObject *obj, jsid id, jsval *vp);
        1234                 :
        1235                 : /*
        1236                 :  * Set a property named by id in obj, treating the assignment as strict
        1237                 :  * mode code if strict is true. Note the jsid id type -- id may be a string
        1238                 :  * (Unicode property identifier) or an int (element index). The *vp out
        1239                 :  * parameter, on success, is the new property value after the
        1240                 :  * set.
        1241                 :  */
        1242                 : typedef JSBool
        1243                 : (* JSStrictPropertyOp)(JSContext *cx, JSObject *obj, jsid id, JSBool strict, jsval *vp);
        1244                 :
        1245                 : /*
        1246                 :  * This function type is used for callbacks that enumerate the properties of
        1247                 :  * a JSObject.  The behavior depends on the value of enum_op:
        1248                 :  *
        1249                 :  *  JSENUMERATE_INIT
        1250                 :  *    A new, opaque iterator state should be allocated and stored in *statep.
        1251                 :  *    (You can use PRIVATE_TO_JSVAL() to tag the pointer to be stored).
        1252                 :  *
        1253                 :  *    The number of properties that will be enumerated should be returned as
        1254                 :  *    an integer jsval in *idp, if idp is non-null, and provided the number of
        1255                 :  *    enumerable properties is known.  If idp is non-null and the number of
        1256                 :  *    enumerable properties can't be computed in advance, *idp should be set
        1257                 :  *    to JSVAL_ZERO.
        1258                 :  *
        1259                 :  *  JSENUMERATE_INIT_ALL
        1260                 :  *    Used identically to JSENUMERATE_INIT, but exposes all properties of the
        1261                 :  *    object regardless of enumerability.
        1262                 :  *
        1263                 :  *  JSENUMERATE_NEXT
        1264                 :  *    A previously allocated opaque iterator state is passed in via statep.
        1265                 :  *    Return the next jsid in the iteration using *idp.  The opaque iterator
        1266                 :  *    state pointed at by statep is destroyed and *statep is set to JSVAL_NULL
        1267                 :  *    if there are no properties left to enumerate.
        1268                 :  *
        1269                 :  *  JSENUMERATE_DESTROY
        1270                 :  *    Destroy the opaque iterator state previously allocated in *statep by a
        1271                 :  *    call to this function when enum_op was JSENUMERATE_INIT or
        1272                 :  *    JSENUMERATE_INIT_ALL.
        1273                 :  *
        1274                 :  * The return value is used to indicate success, with a value of JS_FALSE
        1275                 :  * indicating failure.
        1276                 :  */
        1277                 : typedef JSBool
        1278                 : (* JSNewEnumerateOp)(JSContext *cx, JSObject *obj, JSIterateOp enum_op,
        1279                 :                      jsval *statep, jsid *idp);
        1280                 :
        1281                 : /*
        1282                 :  * The old-style JSClass.enumerate op should define all lazy properties not
        1283                 :  * yet reflected in obj.
        1284                 :  */
        1285                 : typedef JSBool
        1286                 : (* JSEnumerateOp)(JSContext *cx, JSObject *obj);
        1287                 :
        1288                 : /*
        1289                 :  * Resolve a lazy property named by id in obj by defining it directly in obj.
        1290                 :  * Lazy properties are those reflected from some peer native property space
        1291                 :  * (e.g., the DOM attributes for a given node reflected as obj) on demand.
        1292                 :  *
        1293                 :  * JS looks for a property in an object, and if not found, tries to resolve
        1294                 :  * the given id.  If resolve succeeds, the engine looks again in case resolve
        1295                 :  * defined obj[id].  If no such property exists directly in obj, the process
        1296                 :  * is repeated with obj's prototype, etc.
        1297                 :  *
        1298                 :  * NB: JSNewResolveOp provides a cheaper way to resolve lazy properties.
        1299                 :  */
        1300                 : typedef JSBool
        1301                 : (* JSResolveOp)(JSContext *cx, JSObject *obj, jsid id);
        1302                 :
        1303                 : /*
        1304                 :  * Like JSResolveOp, but flags provide contextual information as follows:
        1305                 :  *
        1306                 :  *  JSRESOLVE_QUALIFIED   a qualified property id: obj.id or obj[id], not id
        1307                 :  *  JSRESOLVE_ASSIGNING   obj[id] is on the left-hand side of an assignment
        1308                 :  *  JSRESOLVE_DETECTING   'if (o.p)...' or similar detection opcode sequence
        1309                 :  *  JSRESOLVE_DECLARING   var, const, or function prolog declaration opcode
        1310                 :  *  JSRESOLVE_CLASSNAME   class name used when constructing
        1311                 :  *
        1312                 :  * The *objp out parameter, on success, should be null to indicate that id
        1313                 :  * was not resolved; and non-null, referring to obj or one of its prototypes,
        1314                 :  * if id was resolved.
        1315                 :  *
        1316                 :  * This hook instead of JSResolveOp is called via the JSClass.resolve member
        1317                 :  * if JSCLASS_NEW_RESOLVE is set in JSClass.flags.
        1318                 :  *
        1319                 :  * Setting JSCLASS_NEW_RESOLVE and JSCLASS_NEW_RESOLVE_GETS_START further
        1320                 :  * extends this hook by passing in the starting object on the prototype chain
        1321                 :  * via *objp.  Thus a resolve hook implementation may define the property id
        1322                 :  * being resolved in the object in which the id was first sought, rather than
        1323                 :  * in a prototype object whose class led to the resolve hook being called.
        1324                 :  *
        1325                 :  * When using JSCLASS_NEW_RESOLVE_GETS_START, the resolve hook must therefore
        1326                 :  * null *objp to signify "not resolved".  With only JSCLASS_NEW_RESOLVE and no
        1327                 :  * JSCLASS_NEW_RESOLVE_GETS_START, the hook can assume *objp is null on entry.
        1328                 :  * This is not good practice, but enough existing hook implementations count
        1329                 :  * on it that we can't break compatibility by passing the starting object in
        1330                 :  * *objp without a new JSClass flag.
        1331                 :  */
        1332                 : typedef JSBool
        1333                 : (* JSNewResolveOp)(JSContext *cx, JSObject *obj, jsid id, unsigned flags,
        1334                 :                    JSObject **objp);
        1335                 :
        1336                 : /*
        1337                 :  * Convert obj to the given type, returning true with the resulting value in
        1338                 :  * *vp on success, and returning false on error or exception.
        1339                 :  */
        1340                 : typedef JSBool
        1341                 : (* JSConvertOp)(JSContext *cx, JSObject *obj, JSType type, jsval *vp);
        1342                 :
        1343                 : /*
        1344                 :  * Delegate typeof to an object so it can cloak a primitive or another object.
        1345                 :  */
        1346                 : typedef JSType
        1347                 : (* JSTypeOfOp)(JSContext *cx, JSObject *obj);
        1348                 :
        1349                 : typedef struct JSFreeOp JSFreeOp;
        1350                 :
        1351                 : struct JSFreeOp {
        1352                 : #ifndef __cplusplus
        1353                 :     JSRuntime   *runtime;
        1354                 : #else
        1355                 :   private:
        1356                 :     JSRuntime   *runtime_;
        1357                 :
        1358                 :   protected:
        1359           95615 :     JSFreeOp(JSRuntime *rt)
        1360           95615 :       : runtime_(rt) { }
        1361                 :
        1362                 :   public:
        1363        29243256 :     JSRuntime *runtime() const {
        1364        29243256 :         return runtime_;
        1365                 :     }
        1366                 : #endif
        1367                 : };
        1368                 :
        1369                 : /*
        1370                 :  * Finalize obj, which the garbage collector has determined to be unreachable
        1371                 :  * from other live objects or from GC roots.  Obviously, finalizers must never
        1372                 :  * store a reference to obj.
        1373                 :  */
        1374                 : typedef void
        1375                 : (* JSFinalizeOp)(JSFreeOp *fop, JSObject *obj);
        1376                 :
        1377                 : /*
        1378                 :  * Finalizes external strings created by JS_NewExternalString.
        1379                 :  */
        1380                 : typedef struct JSStringFinalizer JSStringFinalizer;
        1381                 :
        1382                 : struct JSStringFinalizer {
        1383                 :     void (*finalize)(const JSStringFinalizer *fin, jschar *chars);
        1384                 : };
        1385                 :
        1386                 : /*
        1387                 :  * JSClass.checkAccess type: check whether obj[id] may be accessed per mode,
        1388                 :  * returning false on error/exception, true on success with obj[id]'s last-got
        1389                 :  * value in *vp, and its attributes in *attrsp.  As for JSPropertyOp above, id
        1390                 :  * is either a string or an int jsval.
        1391                 :  */
        1392                 : typedef JSBool
        1393                 : (* JSCheckAccessOp)(JSContext *cx, JSObject *obj, jsid id, JSAccessMode mode,
        1394                 :                     jsval *vp);
        1395                 :
        1396                 : /*
        1397                 :  * Check whether v is an instance of obj.  Return false on error or exception,
        1398                 :  * true on success with JS_TRUE in *bp if v is an instance of obj, JS_FALSE in
        1399                 :  * *bp otherwise.
        1400                 :  */
        1401                 : typedef JSBool
        1402                 : (* JSHasInstanceOp)(JSContext *cx, JSObject *obj, const jsval *v, JSBool *bp);
        1403                 :
        1404                 : /*
        1405                 :  * Function type for trace operation of the class called to enumerate all
        1406                 :  * traceable things reachable from obj's private data structure. For each such
        1407                 :  * thing, a trace implementation must call
        1408                 :  *
        1409                 :  *    JS_CallTracer(trc, thing, kind);
        1410                 :  *
        1411                 :  * or one of its convenience macros as described in jsapi.h.
        1412                 :  *
        1413                 :  * JSTraceOp implementation can assume that no other threads mutates object
        1414                 :  * state. It must not change state of the object or corresponding native
        1415                 :  * structures. The only exception for this rule is the case when the embedding
        1416                 :  * needs a tight integration with GC. In that case the embedding can check if
        1417                 :  * the traversal is a part of the marking phase through calling
        1418                 :  * JS_IsGCMarkingTracer and apply a special code like emptying caches or
        1419                 :  * marking its native structures.
        1420                 :  */
        1421                 : typedef void
        1422                 : (* JSTraceOp)(JSTracer *trc, JSObject *obj);
        1423                 :
        1424                 : /*
        1425                 :  * DEBUG only callback that JSTraceOp implementation can provide to return
        1426                 :  * a string describing the reference traced with JS_CallTracer.
        1427                 :  */
        1428                 : typedef void
        1429                 : (* JSTraceNamePrinter)(JSTracer *trc, char *buf, size_t bufsize);
        1430                 :
        1431                 : typedef JSBool
        1432                 : (* JSEqualityOp)(JSContext *cx, JSObject *obj, const jsval *v, JSBool *bp);
        1433                 :
        1434                 : /*
        1435                 :  * Typedef for native functions called by the JS VM.
        1436                 :  *
        1437                 :  * See jsapi.h, the JS_CALLEE, JS_THIS, etc. macros.
        1438                 :  */
        1439                 :
        1440                 : typedef JSBool
        1441                 : (* JSNative)(JSContext *cx, unsigned argc, jsval *vp);
        1442                 :
        1443                 : /* Callbacks and their arguments. */
        1444                 :
        1445                 : typedef enum JSContextOp {
        1446                 :     JSCONTEXT_NEW,
        1447                 :     JSCONTEXT_DESTROY
        1448                 : } JSContextOp;
        1449                 :
        1450                 : /*
        1451                 :  * The possible values for contextOp when the runtime calls the callback are:
        1452                 :  *   JSCONTEXT_NEW      JS_NewContext successfully created a new JSContext
        1453                 :  *                      instance. The callback can initialize the instance as
        1454                 :  *                      required. If the callback returns false, the instance
        1455                 :  *                      will be destroyed and JS_NewContext returns null. In
        1456                 :  *                      this case the callback is not called again.
        1457                 :  *   JSCONTEXT_DESTROY  One of JS_DestroyContext* methods is called. The
        1458                 :  *                      callback may perform its own cleanup and must always
        1459                 :  *                      return true.
        1460                 :  *   Any other value    For future compatibility the callback must do nothing
        1461                 :  *                      and return true in this case.
        1462                 :  */
        1463                 : typedef JSBool
        1464                 : (* JSContextCallback)(JSContext *cx, unsigned contextOp);
        1465                 :
        1466                 : typedef enum JSGCStatus {
        1467                 :     JSGC_BEGIN,
        1468                 :     JSGC_END
        1469                 : } JSGCStatus;
        1470                 :
        1471                 : typedef void
        1472                 : (* JSGCCallback)(JSRuntime *rt, JSGCStatus status);
        1473                 :
        1474                 : typedef enum JSFinalizeStatus {
        1475                 :     JSFINALIZE_START,
        1476                 :     JSFINALIZE_END
        1477                 : } JSFinalizeStatus;
        1478                 :
        1479                 : typedef void
        1480                 : (* JSFinalizeCallback)(JSFreeOp *fop, JSFinalizeStatus status);
        1481                 :
        1482                 : /*
        1483                 :  * Generic trace operation that calls JS_CallTracer on each traceable thing
        1484                 :  * stored in data.
        1485                 :  */
        1486                 : typedef void
        1487                 : (* JSTraceDataOp)(JSTracer *trc, void *data);
        1488                 :
        1489                 : typedef JSBool
        1490                 : (* JSOperationCallback)(JSContext *cx);
        1491                 :
        1492                 : typedef void
        1493                 : (* JSErrorReporter)(JSContext *cx, const char *message, JSErrorReport *report);
        1494                 :
        1495                 : #ifdef MOZ_TRACE_JSCALLS
        1496                 : typedef void
        1497                 : (* JSFunctionCallback)(const JSFunction *fun,
        1498                 :                        const JSScript *scr,
        1499                 :                        const JSContext *cx,
        1500                 :                        int entering);
        1501                 : #endif
        1502                 :
        1503                 : /*
        1504                 :  * Possible exception types. These types are part of a JSErrorFormatString
        1505                 :  * structure. They define which error to throw in case of a runtime error.
        1506                 :  * JSEXN_NONE marks an unthrowable error.
        1507                 :  */
        1508                 : typedef enum JSExnType {
        1509                 :     JSEXN_NONE = -1,
        1510                 :       JSEXN_ERR,
        1511                 :         JSEXN_INTERNALERR,
        1512                 :         JSEXN_EVALERR,
        1513                 :         JSEXN_RANGEERR,
        1514                 :         JSEXN_REFERENCEERR,
        1515                 :         JSEXN_SYNTAXERR,
        1516                 :         JSEXN_TYPEERR,
        1517                 :         JSEXN_URIERR,
        1518                 :         JSEXN_LIMIT
        1519                 : } JSExnType;
        1520                 :
        1521                 : typedef struct JSErrorFormatString {
        1522                 :     /* The error format string (UTF-8 if js_CStringsAreUTF8). */
        1523                 :     const char *format;
        1524                 :
        1525                 :     /* The number of arguments to expand in the formatted error message. */
        1526                 :     uint16_t argCount;
        1527                 :
        1528                 :     /* One of the JSExnType constants above. */
        1529                 :     int16_t exnType;
        1530                 : } JSErrorFormatString;
        1531                 :
        1532                 : typedef const JSErrorFormatString *
        1533                 : (* JSErrorCallback)(void *userRef, const char *locale,
        1534                 :                     const unsigned errorNumber);
        1535                 :
        1536                 : #ifdef va_start
        1537                 : #define JS_ARGUMENT_FORMATTER_DEFINED 1
        1538                 :
        1539                 : typedef JSBool
        1540                 : (* JSArgumentFormatter)(JSContext *cx, const char *format, JSBool fromJS,
        1541                 :                         jsval **vpp, va_list *app);
        1542                 : #endif
        1543                 :
        1544                 : typedef JSBool
        1545                 : (* JSLocaleToUpperCase)(JSContext *cx, JSString *src, jsval *rval);
        1546                 :
        1547                 : typedef JSBool
        1548                 : (* JSLocaleToLowerCase)(JSContext *cx, JSString *src, jsval *rval);
        1549                 :
        1550                 : typedef JSBool
        1551                 : (* JSLocaleCompare)(JSContext *cx, JSString *src1, JSString *src2,
        1552                 :                     jsval *rval);
        1553                 :
        1554                 : typedef JSBool
        1555                 : (* JSLocaleToUnicode)(JSContext *cx, const char *src, jsval *rval);
        1556                 :
        1557                 : /*
        1558                 :  * Security protocol types.
        1559                 :  */
        1560                 :
        1561                 : typedef void
        1562                 : (* JSDestroyPrincipalsOp)(JSPrincipals *principals);
        1563                 :
        1564                 : typedef JSBool
        1565                 : (* JSSubsumePrincipalsOp)(JSPrincipals *principals1, JSPrincipals *principals2);
        1566                 :
        1567                 : /*
        1568                 :  * Return a weak reference to the principals associated with obj, possibly via
        1569                 :  * the immutable parent chain leading from obj to a top-level container (e.g.,
        1570                 :  * a window object in the DOM level 0).  If there are no principals associated
        1571                 :  * with obj, return null.  Therefore null does not mean an error was reported;
        1572                 :  * in no event should an error be reported or an exception be thrown by this
        1573                 :  * callback's implementation.
        1574                 :  */
        1575                 : typedef JSPrincipals *
        1576                 : (* JSObjectPrincipalsFinder)(JSObject *obj);
        1577                 :
        1578                 : /*
        1579                 :  * Used to check if a CSP instance wants to disable eval() and friends.
        1580                 :  * See js_CheckCSPPermitsJSAction() in jsobj.
        1581                 :  */
        1582                 : typedef JSBool
        1583                 : (* JSCSPEvalChecker)(JSContext *cx);
        1584                 :
        1585                 : /*
        1586                 :  * Security callbacks for pushing and popping context principals. These are only
        1587                 :  * temporarily necessary and will hopefully be gone again in a matter of weeks.
        1588                 :  */
        1589                 : typedef JSBool
        1590                 : (* JSPushContextPrincipalOp)(JSContext *cx, JSPrincipals *principals);
        1591                 :
        1592                 : typedef JSBool
        1593                 : (* JSPopContextPrincipalOp)(JSContext *cx);
        1594                 :
        1595                 : /*
        1596                 :  * Callback used to ask the embedding for the cross compartment wrapper handler
        1597                 :  * that implements the desired prolicy for this kind of object in the
        1598                 :  * destination compartment.
        1599                 :  */
        1600                 : typedef JSObject *
        1601                 : (* JSWrapObjectCallback)(JSContext *cx, JSObject *obj, JSObject *proto, JSObject *parent,
        1602                 :                          unsigned flags);
        1603                 :
        1604                 : /*
        1605                 :  * Callback used by the wrap hook to ask the embedding to prepare an object
        1606                 :  * for wrapping in a context. This might include unwrapping other wrappers
        1607                 :  * or even finding a more suitable object for the new compartment.
        1608                 :  */
        1609                 : typedef JSObject *
        1610                 : (* JSPreWrapCallback)(JSContext *cx, JSObject *scope, JSObject *obj, unsigned flags);
        1611                 :
        1612                 : typedef void
        1613                 : (* JSDestroyCompartmentCallback)(JSFreeOp *fop, JSCompartment *compartment);
        1614                 :
        1615                 : /*
        1616                 :  * Read structured data from the reader r. This hook is used to read a value
        1617                 :  * previously serialized by a call to the WriteStructuredCloneOp hook.
        1618                 :  *
        1619                 :  * tag and data are the pair of uint32_t values from the header. The callback
        1620                 :  * may use the JS_Read* APIs to read any other relevant parts of the object
        1621                 :  * from the reader r. closure is any value passed to the JS_ReadStructuredClone
        1622                 :  * function. Return the new object on success, NULL on error/exception.
        1623                 :  */
        1624                 : typedef JSObject *(*ReadStructuredCloneOp)(JSContext *cx, JSStructuredCloneReader *r,
        1625                 :                                            uint32_t tag, uint32_t data, void *closure);
        1626                 :
        1627                 : /*
        1628                 :  * Structured data serialization hook. The engine can write primitive values,
        1629                 :  * Objects, Arrays, Dates, RegExps, TypedArrays, and ArrayBuffers. Any other
        1630                 :  * type of object requires application support. This callback must first use
        1631                 :  * the JS_WriteUint32Pair API to write an object header, passing a value
        1632                 :  * greater than JS_SCTAG_USER to the tag parameter. Then it can use the
        1633                 :  * JS_Write* APIs to write any other relevant parts of the value v to the
        1634                 :  * writer w. closure is any value passed to the JS_WriteStructuredCLone function.
        1635                 :  *
        1636                 :  * Return true on success, false on error/exception.
        1637                 :  */
        1638                 : typedef JSBool (*WriteStructuredCloneOp)(JSContext *cx, JSStructuredCloneWriter *w,
        1639                 :                                          JSObject *obj, void *closure);
        1640                 :
        1641                 : /*
        1642                 :  * This is called when JS_WriteStructuredClone finds that the object to be
        1643                 :  * written is recursive. To follow HTML5, the application must throw a
        1644                 :  * DATA_CLONE_ERR DOMException. errorid is always JS_SCERR_RECURSION.
        1645                 :  */
        1646                 : typedef void (*StructuredCloneErrorOp)(JSContext *cx, uint32_t errorid);
        1647                 :
        1648                 : /************************************************************************/
        1649                 :
        1650                 : JS_BEGIN_EXTERN_C
        1651                 :
        1652                 : /*
        1653                 :  * Silence warning about returning JS::Value (aka jsval) from functions with C
        1654                 :  * linkage. For C JSAPI clients, jsval will be jsval_layout, which should be
        1655                 :  * ABI compatible.
        1656                 :  */
        1657                 : #ifdef _MSC_VER
        1658                 : # pragma warning(disable:4190)
        1659                 : #endif
        1660                 :
        1661                 : /************************************************************************/
        1662                 :
        1663                 : /*
        1664                 :  * JS constants. For efficiency, prefer predicates (e.g., JSVAL_IS_NULL).
        1665                 :  * N.B. These constants are initialized at startup.
        1666                 :  */
        1667                 : extern JS_PUBLIC_DATA(const jsval) JSVAL_NULL;
        1668                 : extern JS_PUBLIC_DATA(const jsval) JSVAL_ZERO;
        1669                 : extern JS_PUBLIC_DATA(const jsval) JSVAL_ONE;
        1670                 : extern JS_PUBLIC_DATA(const jsval) JSVAL_FALSE;
        1671                 : extern JS_PUBLIC_DATA(const jsval) JSVAL_TRUE;
        1672                 : extern JS_PUBLIC_DATA(const jsval) JSVAL_VOID;
        1673                 :
        1674                 : /************************************************************************/
        1675                 :
        1676                 : static JS_ALWAYS_INLINE JSBool
        1677           15041 : JSVAL_IS_NULL(jsval v)
        1678                 : {
        1679           15041 :     return JSVAL_IS_NULL_IMPL(JSVAL_TO_IMPL(v));
        1680                 : }
        1681                 :
        1682                 : static JS_ALWAYS_INLINE JSBool
        1683        20376326 : JSVAL_IS_VOID(jsval v)
        1684                 : {
        1685        20376326 :     return JSVAL_IS_UNDEFINED_IMPL(JSVAL_TO_IMPL(v));
        1686                 : }
        1687                 :
        1688                 : static JS_ALWAYS_INLINE JSBool
        1689         5066044 : JSVAL_IS_INT(jsval v)
        1690                 : {
        1691         5066044 :     return JSVAL_IS_INT32_IMPL(JSVAL_TO_IMPL(v));
        1692                 : }
        1693                 :
        1694                 : static JS_ALWAYS_INLINE int32_t
        1695         3642384 : JSVAL_TO_INT(jsval v)
        1696                 : {
        1697         3642384 :     JS_ASSERT(JSVAL_IS_INT(v));
        1698         3642384 :     return JSVAL_TO_INT32_IMPL(JSVAL_TO_IMPL(v));
        1699                 : }
        1700                 :
        1701                 : static JS_ALWAYS_INLINE jsval
        1702         2499690 : INT_TO_JSVAL(int32_t i)
        1703                 : {
        1704         2499690 :     return IMPL_TO_JSVAL(INT32_TO_JSVAL_IMPL(i));
        1705                 : }
        1706                 :
        1707                 : static JS_ALWAYS_INLINE JSBool
        1708           23517 : JSVAL_IS_DOUBLE(jsval v)
        1709                 : {
        1710           23517 :     return JSVAL_IS_DOUBLE_IMPL(JSVAL_TO_IMPL(v));
        1711                 : }
        1712                 :
        1713                 : static JS_ALWAYS_INLINE double
        1714              27 : JSVAL_TO_DOUBLE(jsval v)
        1715                 : {
        1716                 :     jsval_layout l;
        1717              27 :     JS_ASSERT(JSVAL_IS_DOUBLE(v));
        1718              27 :     l = JSVAL_TO_IMPL(v);
        1719              27 :     return l.asDouble;
        1720                 : }
        1721                 :
        1722                 : static JS_ALWAYS_INLINE jsval
        1723              51 : DOUBLE_TO_JSVAL(double d)
        1724                 : {
        1725                 :     /* This is a manually inlined version of:
        1726                 :      *    d = JS_CANONICALIZE_NAN(d);
        1727                 :      *    return IMPL_TO_JSVAL(DOUBLE_TO_JSVAL_IMPL(d));
        1728                 :      * because GCC from XCode 3.1.4 miscompiles the above code. */
        1729                 :     jsval_layout l;
        1730              51 :     if (JS_UNLIKELY(d != d)) {
        1731              18 :         l.asBits = 0x7FF8000000000000LL;
        1732                 :     } else {
        1733              33 :         l.asDouble = d;
        1734                 :     }
        1735              51 :     return IMPL_TO_JSVAL(l);
        1736                 : }
        1737                 :
        1738                 : static JS_ALWAYS_INLINE jsval
        1739               9 : UINT_TO_JSVAL(uint32_t i)
        1740                 : {
        1741               9 :     if (i <= JSVAL_INT_MAX)
        1742               9 :         return INT_TO_JSVAL((int32_t)i);
        1743               0 :     return DOUBLE_TO_JSVAL((double)i);
        1744                 : }
        1745                 :
        1746                 : static JS_ALWAYS_INLINE JSBool
        1747              63 : JSVAL_IS_NUMBER(jsval v)
        1748                 : {
        1749              63 :     return JSVAL_IS_NUMBER_IMPL(JSVAL_TO_IMPL(v));
        1750                 : }
        1751                 :
        1752                 : static JS_ALWAYS_INLINE JSBool
        1753           73131 : JSVAL_IS_STRING(jsval v)
        1754                 : {
        1755           73131 :     return JSVAL_IS_STRING_IMPL(JSVAL_TO_IMPL(v));
        1756                 : }
        1757                 :
        1758                 : static JS_ALWAYS_INLINE JSString *
        1759           18230 : JSVAL_TO_STRING(jsval v)
        1760                 : {
        1761           18230 :     JS_ASSERT(JSVAL_IS_STRING(v));
        1762           18230 :     return JSVAL_TO_STRING_IMPL(JSVAL_TO_IMPL(v));
        1763                 : }
        1764                 :
        1765                 : static JS_ALWAYS_INLINE jsval
        1766         4386826 : STRING_TO_JSVAL(JSString *str)
        1767                 : {
        1768         4386826 :     return IMPL_TO_JSVAL(STRING_TO_JSVAL_IMPL(str));
        1769                 : }
        1770                 :
        1771                 : static JS_ALWAYS_INLINE JSBool
        1772          119956 : JSVAL_IS_OBJECT(jsval v)
        1773                 : {
        1774          119956 :     return JSVAL_IS_OBJECT_OR_NULL_IMPL(JSVAL_TO_IMPL(v));
        1775                 : }
        1776                 :
        1777                 : static JS_ALWAYS_INLINE JSObject *
        1778          119068 : JSVAL_TO_OBJECT(jsval v)
        1779                 : {
        1780          119068 :     JS_ASSERT(JSVAL_IS_OBJECT(v));
        1781          119068 :     return JSVAL_TO_OBJECT_IMPL(JSVAL_TO_IMPL(v));
        1782                 : }
        1783                 :
        1784                 : static JS_ALWAYS_INLINE jsval
        1785         4330567 : OBJECT_TO_JSVAL(JSObject *obj)
        1786                 : {
        1787         4330567 :     if (obj)
        1788         4330504 :         return IMPL_TO_JSVAL(OBJECT_TO_JSVAL_IMPL(obj));
        1789              63 :     return JSVAL_NULL;
        1790                 : }
        1791                 :
        1792                 : static JS_ALWAYS_INLINE JSBool
        1793            1035 : JSVAL_IS_BOOLEAN(jsval v)
        1794                 : {
        1795            1035 :     return JSVAL_IS_BOOLEAN_IMPL(JSVAL_TO_IMPL(v));
        1796                 : }
        1797                 :
        1798                 : static JS_ALWAYS_INLINE JSBool
        1799             486 : JSVAL_TO_BOOLEAN(jsval v)
        1800                 : {
        1801             486 :     JS_ASSERT(JSVAL_IS_BOOLEAN(v));
        1802             486 :     return JSVAL_TO_BOOLEAN_IMPL(JSVAL_TO_IMPL(v));
        1803                 : }
        1804                 :
        1805                 : static JS_ALWAYS_INLINE jsval
        1806               0 : BOOLEAN_TO_JSVAL(JSBool b)
        1807                 : {
        1808               0 :     return IMPL_TO_JSVAL(BOOLEAN_TO_JSVAL_IMPL(b));
        1809                 : }
        1810                 :
        1811                 : static JS_ALWAYS_INLINE JSBool
        1812           84429 : JSVAL_IS_PRIMITIVE(jsval v)
        1813                 : {
        1814           84429 :     return JSVAL_IS_PRIMITIVE_IMPL(JSVAL_TO_IMPL(v));
        1815                 : }
        1816                 :
        1817                 : static JS_ALWAYS_INLINE JSBool
        1818              48 : JSVAL_IS_GCTHING(jsval v)
        1819                 : {
        1820              48 :     return JSVAL_IS_GCTHING_IMPL(JSVAL_TO_IMPL(v));
        1821                 : }
        1822                 :
        1823                 : static JS_ALWAYS_INLINE void *
        1824               0 : JSVAL_TO_GCTHING(jsval v)
        1825                 : {
        1826               0 :     JS_ASSERT(JSVAL_IS_GCTHING(v));
        1827               0 :     return JSVAL_TO_GCTHING_IMPL(JSVAL_TO_IMPL(v));
        1828                 : }
        1829                 :
        1830                 : /* To be GC-safe, privates are tagged as doubles. */
        1831                 :
        1832                 : static JS_ALWAYS_INLINE jsval
        1833          741834 : PRIVATE_TO_JSVAL(void *ptr)
        1834                 : {
        1835          741834 :     return IMPL_TO_JSVAL(PRIVATE_PTR_TO_JSVAL_IMPL(ptr));
        1836                 : }
        1837                 :
        1838                 : static JS_ALWAYS_INLINE void *
        1839               0 : JSVAL_TO_PRIVATE(jsval v)
        1840                 : {
        1841               0 :     JS_ASSERT(JSVAL_IS_DOUBLE(v));
        1842               0 :     return JSVAL_TO_PRIVATE_PTR_IMPL(JSVAL_TO_IMPL(v));
        1843                 : }
        1844                 :
        1845                 : /************************************************************************/
        1846                 :
        1847                 : /*
        1848                 :  * A jsid is an identifier for a property or method of an object which is
        1849                 :  * either a 31-bit signed integer, interned string or object. If XML is
        1850                 :  * enabled, there is an additional singleton jsid value; see
        1851                 :  * JS_DEFAULT_XML_NAMESPACE_ID below. Finally, there is an additional jsid
        1852                 :  * value, JSID_VOID, which does not occur in JS scripts but may be used to
        1853                 :  * indicate the absence of a valid jsid.
        1854                 :  *
        1855                 :  * A jsid is not implicitly convertible to or from a jsval; JS_ValueToId or
        1856                 :  * JS_IdToValue must be used instead.
        1857                 :  */
        1858                 :
        1859                 : #define JSID_TYPE_STRING                 0x0
        1860                 : #define JSID_TYPE_INT                    0x1
        1861                 : #define JSID_TYPE_VOID                   0x2
        1862                 : #define JSID_TYPE_OBJECT                 0x4
        1863                 : #define JSID_TYPE_DEFAULT_XML_NAMESPACE  0x6
        1864                 : #define JSID_TYPE_MASK                   0x7
        1865                 :
        1866                 : /*
        1867                 :  * Avoid using canonical 'id' for jsid parameters since this is a magic word in
        1868                 :  * Objective-C++ which, apparently, wants to be able to #include jsapi.h.
        1869                 :  */
        1870                 : #define id iden
        1871                 :
        1872                 : static JS_ALWAYS_INLINE JSBool
        1873       954571911 : JSID_IS_STRING(jsid id)
        1874                 : {
        1875       954571911 :     return (JSID_BITS(id) & JSID_TYPE_MASK) == 0;
        1876                 : }
        1877                 :
        1878                 : static JS_ALWAYS_INLINE JSString *
        1879       377419279 : JSID_TO_STRING(jsid id)
        1880                 : {
        1881       377419279 :     JS_ASSERT(JSID_IS_STRING(id));
        1882       377419279 :     return (JSString *)JSID_BITS(id);
        1883                 : }
        1884                 :
        1885                 : static JS_ALWAYS_INLINE JSBool
        1886                 : JSID_IS_ZERO(jsid id)
        1887                 : {
        1888                 :     return JSID_BITS(id) == 0;
        1889                 : }
        1890                 :
        1891                 : JS_PUBLIC_API(JSBool)
        1892                 : JS_StringHasBeenInterned(JSContext *cx, JSString *str);
        1893                 :
        1894                 : /*
        1895                 :  * Only JSStrings that have been interned via the JSAPI can be turned into
        1896                 :  * jsids by API clients.
        1897                 :  *
        1898                 :  * N.B. if a jsid is backed by a string which has not been interned, that
        1899                 :  * string must be appropriately rooted to avoid being collected by the GC.
        1900                 :  */
        1901                 : static JS_ALWAYS_INLINE jsid
        1902                 : INTERNED_STRING_TO_JSID(JSContext *cx, JSString *str)
        1903                 : {
        1904                 :     jsid id;
        1905                 :     JS_ASSERT(str);
        1906                 :     JS_ASSERT(((size_t)str & JSID_TYPE_MASK) == 0);
        1907                 : #ifdef DEBUG
        1908                 :     JS_ASSERT(JS_StringHasBeenInterned(cx, str));
        1909                 : #else
        1910                 :     (void)cx;
        1911                 : #endif
        1912                 :     JSID_BITS(id) = (size_t)str;
        1913                 :     return id;
        1914                 : }
        1915                 :
        1916                 : static JS_ALWAYS_INLINE JSBool
        1917       244949179 : JSID_IS_INT(jsid id)
        1918                 : {
        1919       244949179 :     return !!(JSID_BITS(id) & JSID_TYPE_INT);
        1920                 : }
        1921                 :
        1922                 : static JS_ALWAYS_INLINE int32_t
        1923        70169071 : JSID_TO_INT(jsid id)
        1924                 : {
        1925        70169071 :     JS_ASSERT(JSID_IS_INT(id));
        1926        70169071 :     return ((int32_t)JSID_BITS(id)) >> 1;
        1927                 : }
        1928                 :
        1929                 : /*
        1930                 :  * Note: when changing these values, verify that their use in
        1931                 :  * js_CheckForStringIndex is still valid.
        1932                 :  */
        1933                 : #define JSID_INT_MIN  (-(1 << 30))
        1934                 : #define JSID_INT_MAX  ((1 << 30) - 1)
        1935                 :
        1936                 : static JS_ALWAYS_INLINE JSBool
        1937        81245204 : INT_FITS_IN_JSID(int32_t i)
        1938                 : {
        1939                 :     return ((uint32_t)(i) - (uint32_t)JSID_INT_MIN <=
        1940        81245204 :             (uint32_t)(JSID_INT_MAX - JSID_INT_MIN));
        1941                 : }
        1942                 :
        1943                 : static JS_ALWAYS_INLINE jsid
        1944        62264723 : INT_TO_JSID(int32_t i)
        1945                 : {
        1946                 :     jsid id;
        1947        62264723 :     JS_ASSERT(INT_FITS_IN_JSID(i));
        1948        62264723 :     JSID_BITS(id) = ((i << 1) | JSID_TYPE_INT);
        1949                 :     return id;
        1950                 : }
        1951                 :
        1952                 : static JS_ALWAYS_INLINE JSBool
        1953        37806967 : JSID_IS_OBJECT(jsid id)
        1954                 : {
        1955                 :     return (JSID_BITS(id) & JSID_TYPE_MASK) == JSID_TYPE_OBJECT &&
        1956        37806967 :            (size_t)JSID_BITS(id) != JSID_TYPE_OBJECT;
        1957                 : }
        1958                 :
        1959                 : static JS_ALWAYS_INLINE JSObject *
        1960             355 : JSID_TO_OBJECT(jsid id)
        1961                 : {
        1962             355 :     JS_ASSERT(JSID_IS_OBJECT(id));
        1963             355 :     return (JSObject *)(JSID_BITS(id) & ~(size_t)JSID_TYPE_MASK);
        1964                 : }
        1965                 :
        1966                 : static JS_ALWAYS_INLINE jsid
        1967              54 : OBJECT_TO_JSID(JSObject *obj)
        1968                 : {
        1969                 :     jsid id;
        1970              54 :     JS_ASSERT(obj != NULL);
        1971              54 :     JS_ASSERT(((size_t)obj & JSID_TYPE_MASK) == 0);
        1972              54 :     JSID_BITS(id) = ((size_t)obj | JSID_TYPE_OBJECT);
        1973                 :     return id;
        1974                 : }
        1975                 :
        1976                 : static JS_ALWAYS_INLINE JSBool
        1977                 : JSID_IS_GCTHING(jsid id)
        1978                 : {
        1979                 :     return JSID_IS_STRING(id) || JSID_IS_OBJECT(id);
        1980                 : }
        1981                 :
        1982                 : static JS_ALWAYS_INLINE void *
        1983                 : JSID_TO_GCTHING(jsid id)
        1984                 : {
        1985                 :     return (void *)(JSID_BITS(id) & ~(size_t)JSID_TYPE_MASK);
        1986                 : }
        1987                 :
        1988                 : /*
        1989                 :  * The magic XML namespace id is not a valid jsid. Global object classes in
        1990                 :  * embeddings that enable JS_HAS_XML_SUPPORT (E4X) should handle this id.
        1991                 :  */
        1992                 :
        1993                 : static JS_ALWAYS_INLINE JSBool
        1994        34379214 : JSID_IS_DEFAULT_XML_NAMESPACE(jsid id)
        1995                 : {
        1996               0 :     JS_ASSERT_IF(((size_t)JSID_BITS(id) & JSID_TYPE_MASK) == JSID_TYPE_DEFAULT_XML_NAMESPACE,
        1997        34379214 :                  JSID_BITS(id) == JSID_TYPE_DEFAULT_XML_NAMESPACE);
        1998        34379214 :     return ((size_t)JSID_BITS(id) == JSID_TYPE_DEFAULT_XML_NAMESPACE);
        1999                 : }
        2000                 :
        2001                 : #ifdef JS_USE_JSID_STRUCT_TYPES
        2002                 : extern JS_PUBLIC_DATA(jsid) JS_DEFAULT_XML_NAMESPACE_ID;
        2003                 : #else
        2004                 : # define JS_DEFAULT_XML_NAMESPACE_ID ((jsid)JSID_TYPE_DEFAULT_XML_NAMESPACE)
        2005                 : #endif
        2006                 :
        2007                 : /*
        2008                 :  * A void jsid is not a valid id and only arises as an exceptional API return
        2009                 :  * value, such as in JS_NextProperty. Embeddings must not pass JSID_VOID into
        2010                 :  * JSAPI entry points expecting a jsid and do not need to handle JSID_VOID in
        2011                 :  * hooks receiving a jsid except when explicitly noted in the API contract.
        2012                 :  */
        2013                 :
        2014                 : static JS_ALWAYS_INLINE JSBool
        2015      1170936686 : JSID_IS_VOID(jsid id)
        2016                 : {
        2017               0 :     JS_ASSERT_IF(((size_t)JSID_BITS(id) & JSID_TYPE_MASK) == JSID_TYPE_VOID,
        2018      1170936686 :                  JSID_BITS(id) == JSID_TYPE_VOID);
        2019      1170936686 :     return ((size_t)JSID_BITS(id) == JSID_TYPE_VOID);
        2020                 : }
        2021                 :
        2022                 : static JS_ALWAYS_INLINE JSBool
        2023              -1 : JSID_IS_EMPTY(jsid id)
        2024                 : {
        2025              -1 :     return ((size_t)JSID_BITS(id) == JSID_TYPE_OBJECT);
        2026                 : }
        2027                 :
        2028                 : #undef id
        2029                 :
        2030                 : #ifdef JS_USE_JSID_STRUCT_TYPES
        2031                 : extern JS_PUBLIC_DATA(jsid) JSID_VOID;
        2032                 : extern JS_PUBLIC_DATA(jsid) JSID_EMPTY;
        2033                 : #else
        2034                 : # define JSID_VOID ((jsid)JSID_TYPE_VOID)
        2035                 : # define JSID_EMPTY ((jsid)JSID_TYPE_OBJECT)
        2036                 : #endif
        2037                 :
        2038                 : /*
        2039                 :  * Returns true iff the given jsval is immune to GC and can be used across
        2040                 :  * multiple JSRuntimes without requiring any conversion API.
        2041                 :  */
        2042                 : static JS_ALWAYS_INLINE JSBool
        2043                 : JSVAL_IS_UNIVERSAL(jsval v)
        2044                 : {
        2045                 :     return !JSVAL_IS_GCTHING(v);
        2046                 : }
        2047                 :
        2048                 : #ifdef __cplusplus
        2049                 :
        2050                 : namespace JS {
        2051                 :
        2052                 : class AutoIdRooter : private AutoGCRooter
        2053          221314 : {
        2054                 :   public:
        2055          221314 :     explicit AutoIdRooter(JSContext *cx, jsid id = INT_TO_JSID(0)
        2056                 :                           JS_GUARD_OBJECT_NOTIFIER_PARAM)
        2057          221314 :       : AutoGCRooter(cx, ID), id_(id)
        2058                 :     {
        2059          221314 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        2060          221314 :     }
        2061                 :
        2062          225778 :     jsid id() {
        2063          225778 :         return id_;
        2064                 :     }
        2065                 :
        2066          221314 :     jsid * addr() {
        2067          221314 :         return &id_;
        2068                 :     }
        2069                 :
        2070                 :     friend void AutoGCRooter::trace(JSTracer *trc);
        2071                 :
        2072                 :   private:
        2073                 :     jsid id_;
        2074                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        2075                 : };
        2076                 :
        2077                 : } /* namespace JS */
        2078                 :
        2079                 : #endif /* __cplusplus */
        2080                 :
        2081                 : /************************************************************************/
        2082                 :
        2083                 : /* Lock and unlock the GC thing held by a jsval. */
        2084                 : #define JSVAL_LOCK(cx,v)        (JSVAL_IS_GCTHING(v)                          \
        2085                 :                                  ? JS_LockGCThing(cx, JSVAL_TO_GCTHING(v))    \
        2086                 :                                  : JS_TRUE)
        2087                 : #define JSVAL_UNLOCK(cx,v)      (JSVAL_IS_GCTHING(v)                          \
        2088                 :                                  ? JS_UnlockGCThing(cx, JSVAL_TO_GCTHING(v))  \
        2089                 :                                  : JS_TRUE)
        2090                 :
        2091                 : /* Property attributes, set in JSPropertySpec and passed to API functions. */
        2092                 : #define JSPROP_ENUMERATE        0x01    /* property is visible to for/in loop */
        2093                 : #define JSPROP_READONLY         0x02    /* not settable: assignment is no-op.
        2094                 :                                            This flag is only valid when neither
        2095                 :                                            JSPROP_GETTER nor JSPROP_SETTER is
        2096                 :                                            set. */
        2097                 : #define JSPROP_PERMANENT        0x04    /* property cannot be deleted */
        2098                 : #define JSPROP_GETTER           0x10    /* property holds getter function */
        2099                 : #define JSPROP_SETTER           0x20    /* property holds setter function */
        2100                 : #define JSPROP_SHARED           0x40    /* don't allocate a value slot for this
        2101                 :                                            property; don't copy the property on
        2102                 :                                            set of the same-named property in an
        2103                 :                                            object that delegates to a prototype
        2104                 :                                            containing this property */
        2105                 : #define JSPROP_INDEX            0x80    /* name is actually (int) index */
        2106                 : #define JSPROP_SHORTID          0x100   /* set in JS_DefineProperty attrs
        2107                 :                                            if getters/setters use a shortid */
        2108                 : #define JSPROP_NATIVE_ACCESSORS 0x08    /* set in JSPropertyDescriptor.flags
        2109                 :                                            if getters/setters are JSNatives */
        2110                 :
        2111                 : /* Function flags, internal use only, returned by JS_GetFunctionFlags. */
        2112                 : #define JSFUN_LAMBDA            0x08    /* expressed, not declared, function */
        2113                 : #define JSFUN_HEAVYWEIGHT       0x80    /* activation requires a Call object */
        2114                 :
        2115                 : #define JSFUN_HEAVYWEIGHT_TEST(f)  ((f) & JSFUN_HEAVYWEIGHT)
        2116                 :
        2117                 : /* 0x0100 is unused */
        2118                 : #define JSFUN_CONSTRUCTOR     0x0200    /* native that can be called as a ctor
        2119                 :                                            without creating a this object */
        2120                 :
        2121                 : #define JSFUN_FLAGS_MASK      0x07f8    /* overlay JSFUN_* attributes --
        2122                 :                                            bits 12-15 are used internally to
        2123                 :                                            flag interpreted functions */
        2124                 :
        2125                 : #define JSFUN_STUB_GSOPS      0x1000    /* use JS_PropertyStub getter/setter
        2126                 :                                            instead of defaulting to class gsops
        2127                 :                                            for property holding function */
        2128                 :
        2129                 : /*
        2130                 :  * Re-use JSFUN_LAMBDA, which applies only to scripted functions, for use in
        2131                 :  * JSFunctionSpec arrays that specify generic native prototype methods, i.e.,
        2132                 :  * methods of a class prototype that are exposed as static methods taking an
        2133                 :  * extra leading argument: the generic |this| parameter.
        2134                 :  *
        2135                 :  * If you set this flag in a JSFunctionSpec struct's flags initializer, then
        2136                 :  * that struct must live at least as long as the native static method object
        2137                 :  * created due to this flag by JS_DefineFunctions or JS_InitClass.  Typically
        2138                 :  * JSFunctionSpec structs are allocated in static arrays.
        2139                 :  */
        2140                 : #define JSFUN_GENERIC_NATIVE    JSFUN_LAMBDA
        2141                 :
        2142                 : /*
        2143                 :  * The first call to JS_CallOnce by any thread in a process will call 'func'.
        2144                 :  * Later calls to JS_CallOnce with the same JSCallOnceType object will be
        2145                 :  * suppressed.
        2146                 :  *
        2147                 :  * Equivalently: each distinct JSCallOnceType object will allow one JS_CallOnce
        2148                 :  * to invoke its JSInitCallback.
        2149                 :  */
        2150                 : extern JS_PUBLIC_API(JSBool)
        2151                 : JS_CallOnce(JSCallOnceType *once, JSInitCallback func);
        2152                 :
        2153                 : /* Microseconds since the epoch, midnight, January 1, 1970 UTC. */
        2154                 : extern JS_PUBLIC_API(int64_t)
        2155                 : JS_Now(void);
        2156                 :
        2157                 : /* Don't want to export data, so provide accessors for non-inline jsvals. */
        2158                 : extern JS_PUBLIC_API(jsval)
        2159                 : JS_GetNaNValue(JSContext *cx);
        2160                 :
        2161                 : extern JS_PUBLIC_API(jsval)
        2162                 : JS_GetNegativeInfinityValue(JSContext *cx);
        2163                 :
        2164                 : extern JS_PUBLIC_API(jsval)
        2165                 : JS_GetPositiveInfinityValue(JSContext *cx);
        2166                 :
        2167                 : extern JS_PUBLIC_API(jsval)
        2168                 : JS_GetEmptyStringValue(JSContext *cx);
        2169                 :
        2170                 : extern JS_PUBLIC_API(JSString *)
        2171                 : JS_GetEmptyString(JSRuntime *rt);
        2172                 :
        2173                 : /*
        2174                 :  * Format is a string of the following characters (spaces are insignificant),
        2175                 :  * specifying the tabulated type conversions:
        2176                 :  *
        2177                 :  *   b      JSBool          Boolean
        2178                 :  *   c      uint16_t/jschar ECMA uint16_t, Unicode char
        2179                 :  *   i      int32_t         ECMA int32_t
        2180                 :  *   u      uint32_t        ECMA uint32_t
        2181                 :  *   j      int32_t         Rounded int32_t (coordinate)
        2182                 :  *   d      double          IEEE double
        2183                 :  *   I      double          Integral IEEE double
        2184                 :  *   S      JSString *      Unicode string, accessed by a JSString pointer
        2185                 :  *   W      jschar *        Unicode character vector, 0-terminated (W for wide)
        2186                 :  *   o      JSObject *      Object reference
        2187                 :  *   f      JSFunction *    Function private
        2188                 :  *   v      jsval           Argument value (no conversion)
        2189                 :  *   *      N/A             Skip this argument (no vararg)
        2190                 :  *   /      N/A             End of required arguments
        2191                 :  *
        2192                 :  * The variable argument list after format must consist of &b, &c, &s, e.g.,
        2193                 :  * where those variables have the types given above.  For the pointer types
        2194                 :  * char *, JSString *, and JSObject *, the pointed-at memory returned belongs
        2195                 :  * to the JS runtime, not to the calling native code.  The runtime promises
        2196                 :  * to keep this memory valid so long as argv refers to allocated stack space
        2197                 :  * (so long as the native function is active).
        2198                 :  *
        2199                 :  * Fewer arguments than format specifies may be passed only if there is a /
        2200                 :  * in format after the last required argument specifier and argc is at least
        2201                 :  * the number of required arguments.  More arguments than format specifies
        2202                 :  * may be passed without error; it is up to the caller to deal with trailing
        2203                 :  * unconverted arguments.
        2204                 :  */
        2205                 : extern JS_PUBLIC_API(JSBool)
        2206                 : JS_ConvertArguments(JSContext *cx, unsigned argc, jsval *argv, const char *format,
        2207                 :                     ...);
        2208                 :
        2209                 : #ifdef va_start
        2210                 : extern JS_PUBLIC_API(JSBool)
        2211                 : JS_ConvertArgumentsVA(JSContext *cx, unsigned argc, jsval *argv,
        2212                 :                       const char *format, va_list ap);
        2213                 : #endif
        2214                 :
        2215                 : #ifdef JS_ARGUMENT_FORMATTER_DEFINED
        2216                 :
        2217                 : /*
        2218                 :  * Add and remove a format string handler for JS_{Convert,Push}Arguments{,VA}.
        2219                 :  * The handler function has this signature:
        2220                 :  *
        2221                 :  *   JSBool MyArgumentFormatter(JSContext *cx, const char *format,
        2222                 :  *                              JSBool fromJS, jsval **vpp, va_list *app);
        2223                 :  *
        2224                 :  * It should return true on success, and return false after reporting an error
        2225                 :  * or detecting an already-reported error.
        2226                 :  *
        2227                 :  * For a given format string, for example "AA", the formatter is called from
        2228                 :  * JS_ConvertArgumentsVA like so:
        2229                 :  *
        2230                 :  *   formatter(cx, "AA...", JS_TRUE, &sp, &ap);
        2231                 :  *
        2232                 :  * sp points into the arguments array on the JS stack, while ap points into
        2233                 :  * the stdarg.h va_list on the C stack.  The JS_TRUE passed for fromJS tells
        2234                 :  * the formatter to convert zero or more jsvals at sp to zero or more C values
        2235                 :  * accessed via pointers-to-values at ap, updating both sp (via *vpp) and ap
        2236                 :  * (via *app) to point past the converted arguments and their result pointers
        2237                 :  * on the C stack.
        2238                 :  *
        2239                 :  * When called from JS_PushArgumentsVA, the formatter is invoked thus:
        2240                 :  *
        2241                 :  *   formatter(cx, "AA...", JS_FALSE, &sp, &ap);
        2242                 :  *
        2243                 :  * where JS_FALSE for fromJS means to wrap the C values at ap according to the
        2244                 :  * format specifier and store them at sp, updating ap and sp appropriately.
        2245                 :  *
        2246                 :  * The "..." after "AA" is the rest of the format string that was passed into
        2247                 :  * JS_{Convert,Push}Arguments{,VA}.  The actual format trailing substring used
        2248                 :  * in each Convert or PushArguments call is passed to the formatter, so that
        2249                 :  * one such function may implement several formats, in order to share code.
        2250                 :  *
        2251                 :  * Remove just forgets about any handler associated with format.  Add does not
        2252                 :  * copy format, it points at the string storage allocated by the caller, which
        2253                 :  * is typically a string constant.  If format is in dynamic storage, it is up
        2254                 :  * to the caller to keep the string alive until Remove is called.
        2255                 :  */
        2256                 : extern JS_PUBLIC_API(JSBool)
        2257                 : JS_AddArgumentFormatter(JSContext *cx, const char *format,
        2258                 :                         JSArgumentFormatter formatter);
        2259                 :
        2260                 : extern JS_PUBLIC_API(void)
        2261                 : JS_RemoveArgumentFormatter(JSContext *cx, const char *format);
        2262                 :
        2263                 : #endif /* JS_ARGUMENT_FORMATTER_DEFINED */
        2264                 :
        2265                 : extern JS_PUBLIC_API(JSBool)
        2266                 : JS_ConvertValue(JSContext *cx, jsval v, JSType type, jsval *vp);
        2267                 :
        2268                 : extern JS_PUBLIC_API(JSBool)
        2269                 : JS_ValueToObject(JSContext *cx, jsval v, JSObject **objp);
        2270                 :
        2271                 : extern JS_PUBLIC_API(JSFunction *)
        2272                 : JS_ValueToFunction(JSContext *cx, jsval v);
        2273                 :
        2274                 : extern JS_PUBLIC_API(JSFunction *)
        2275                 : JS_ValueToConstructor(JSContext *cx, jsval v);
        2276                 :
        2277                 : extern JS_PUBLIC_API(JSString *)
        2278                 : JS_ValueToString(JSContext *cx, jsval v);
        2279                 :
        2280                 : extern JS_PUBLIC_API(JSString *)
        2281                 : JS_ValueToSource(JSContext *cx, jsval v);
        2282                 :
        2283                 : extern JS_PUBLIC_API(JSBool)
        2284                 : JS_ValueToNumber(JSContext *cx, jsval v, double *dp);
        2285                 :
        2286                 : #ifdef __cplusplus
        2287                 : namespace js {
        2288                 : /*
        2289                 :  * DO NOT CALL THIS.  Use JS::ToNumber
        2290                 :  */
        2291                 : extern JS_PUBLIC_API(bool)
        2292                 : ToNumberSlow(JSContext *cx, JS::Value v, double *dp);
        2293                 : } /* namespace js */
        2294                 :
        2295                 : namespace JS {
        2296                 :
        2297                 : /* ES5 9.3 ToNumber. */
        2298                 : JS_ALWAYS_INLINE bool
        2299        87601197 : ToNumber(JSContext *cx, const Value &v, double *out)
        2300                 : {
        2301        87601197 :     AssertArgumentsAreSane(cx, v);
        2302        87601197 :     if (v.isNumber()) {
        2303        87034930 :         *out = v.toNumber();
        2304        87034930 :         return true;
        2305                 :     }
        2306          566267 :     return js::ToNumberSlow(cx, v, out);
        2307                 : }
        2308                 :
        2309                 : } /* namespace JS */
        2310                 : #endif /* __cplusplus */
        2311                 :
        2312                 : extern JS_PUBLIC_API(JSBool)
        2313                 : JS_DoubleIsInt32(double d, int32_t *ip);
        2314                 :
        2315                 : extern JS_PUBLIC_API(int32_t)
        2316                 : JS_DoubleToInt32(double d);
        2317                 :
        2318                 : extern JS_PUBLIC_API(uint32_t)
        2319                 : JS_DoubleToUint32(double d);
        2320                 :
        2321                 : /*
        2322                 :  * Convert a value to a number, then to an int32_t, according to the ECMA rules
        2323                 :  * for ToInt32.
        2324                 :  */
        2325                 : extern JS_PUBLIC_API(JSBool)
        2326                 : JS_ValueToECMAInt32(JSContext *cx, jsval v, int32_t *ip);
        2327                 :
        2328                 : #ifdef __cplusplus
        2329                 : namespace js {
        2330                 : /*
        2331                 :  * DO NOT CALL THIS.  Use JS::ToInt32
        2332                 :  */
        2333                 : extern JS_PUBLIC_API(bool)
        2334                 : ToInt32Slow(JSContext *cx, const JS::Value &v, int32_t *out);
        2335                 : } /* namespace js */
        2336                 :
        2337                 : namespace JS {
        2338                 :
        2339                 : JS_ALWAYS_INLINE bool
        2340       100062834 : ToInt32(JSContext *cx, const js::Value &v, int32_t *out)
        2341                 : {
        2342       100062834 :     AssertArgumentsAreSane(cx, v);
        2343       100062834 :     if (v.isInt32()) {
        2344        98378634 :         *out = v.toInt32();
        2345        98378634 :         return true;
        2346                 :     }
        2347         1684200 :     return js::ToInt32Slow(cx, v, out);
        2348                 : }
        2349                 :
        2350                 : } /* namespace JS */
        2351                 : #endif /* __cplusplus */
        2352                 :
        2353                 : /*
        2354                 :  * Convert a value to a number, then to a uint32_t, according to the ECMA rules
        2355                 :  * for ToUint32.
        2356                 :  */
        2357                 : extern JS_PUBLIC_API(JSBool)
        2358                 : JS_ValueToECMAUint32(JSContext *cx, jsval v, uint32_t *ip);
        2359                 :
        2360                 : /*
        2361                 :  * Convert a value to a number, then to an int32_t if it fits by rounding to
        2362                 :  * nearest; but failing with an error report if the double is out of range
        2363                 :  * or unordered.
        2364                 :  */
        2365                 : extern JS_PUBLIC_API(JSBool)
        2366                 : JS_ValueToInt32(JSContext *cx, jsval v, int32_t *ip);
        2367                 :
        2368                 : /*
        2369                 :  * ECMA ToUint16, for mapping a jsval to a Unicode point.
        2370                 :  */
        2371                 : extern JS_PUBLIC_API(JSBool)
        2372                 : JS_ValueToUint16(JSContext *cx, jsval v, uint16_t *ip);
        2373                 :
        2374                 : extern JS_PUBLIC_API(JSBool)
        2375                 : JS_ValueToBoolean(JSContext *cx, jsval v, JSBool *bp);
        2376                 :
        2377                 : extern JS_PUBLIC_API(JSType)
        2378                 : JS_TypeOfValue(JSContext *cx, jsval v);
        2379                 :
        2380                 : extern JS_PUBLIC_API(const char *)
        2381                 : JS_GetTypeName(JSContext *cx, JSType type);
        2382                 :
        2383                 : extern JS_PUBLIC_API(JSBool)
        2384                 : JS_StrictlyEqual(JSContext *cx, jsval v1, jsval v2, JSBool *equal);
        2385                 :
        2386                 : extern JS_PUBLIC_API(JSBool)
        2387                 : JS_LooselyEqual(JSContext *cx, jsval v1, jsval v2, JSBool *equal);
        2388                 :
        2389                 : extern JS_PUBLIC_API(JSBool)
        2390                 : JS_SameValue(JSContext *cx, jsval v1, jsval v2, JSBool *same);
        2391                 :
        2392                 : /* True iff fun is the global eval function. */
        2393                 : extern JS_PUBLIC_API(JSBool)
        2394                 : JS_IsBuiltinEvalFunction(JSFunction *fun);
        2395                 :
        2396                 : /* True iff fun is the Function constructor. */
        2397                 : extern JS_PUBLIC_API(JSBool)
        2398                 : JS_IsBuiltinFunctionConstructor(JSFunction *fun);
        2399                 :
        2400                 : /************************************************************************/
        2401                 :
        2402                 : /*
        2403                 :  * Initialization, locking, contexts, and memory allocation.
        2404                 :  *
        2405                 :  * It is important that the first runtime and first context be created in a
        2406                 :  * single-threaded fashion, otherwise the behavior of the library is undefined.
        2407                 :  * See: http://developer.mozilla.org/en/docs/Category:JSAPI_Reference
        2408                 :  */
        2409                 : #define JS_NewRuntime       JS_Init
        2410                 : #define JS_DestroyRuntime   JS_Finish
        2411                 : #define JS_LockRuntime      JS_Lock
        2412                 : #define JS_UnlockRuntime    JS_Unlock
        2413                 :
        2414                 : extern JS_PUBLIC_API(JSRuntime *)
        2415                 : JS_NewRuntime(uint32_t maxbytes);
        2416                 :
        2417                 : /* Deprecated. */
        2418                 : #define JS_CommenceRuntimeShutDown(rt) ((void) 0)
        2419                 :
        2420                 : extern JS_PUBLIC_API(void)
        2421                 : JS_DestroyRuntime(JSRuntime *rt);
        2422                 :
        2423                 : extern JS_PUBLIC_API(void)
        2424                 : JS_ShutDown(void);
        2425                 :
        2426                 : JS_PUBLIC_API(void *)
        2427                 : JS_GetRuntimePrivate(JSRuntime *rt);
        2428                 :
        2429                 : extern JS_PUBLIC_API(JSRuntime *)
        2430                 : JS_GetRuntime(JSContext *cx);
        2431                 :
        2432                 : JS_PUBLIC_API(void)
        2433                 : JS_SetRuntimePrivate(JSRuntime *rt, void *data);
        2434                 :
        2435                 : extern JS_PUBLIC_API(void)
        2436                 : JS_BeginRequest(JSContext *cx);
        2437                 :
        2438                 : extern JS_PUBLIC_API(void)
        2439                 : JS_EndRequest(JSContext *cx);
        2440                 :
        2441                 : /* Yield to pending GC operations, regardless of request depth */
        2442                 : extern JS_PUBLIC_API(void)
        2443                 : JS_YieldRequest(JSContext *cx);
        2444                 :
        2445                 : extern JS_PUBLIC_API(unsigned)
        2446                 : JS_SuspendRequest(JSContext *cx);
        2447                 :
        2448                 : extern JS_PUBLIC_API(void)
        2449                 : JS_ResumeRequest(JSContext *cx, unsigned saveDepth);
        2450                 :
        2451                 : extern JS_PUBLIC_API(JSBool)
        2452                 : JS_IsInRequest(JSRuntime *rt);
        2453                 :
        2454                 : extern JS_PUBLIC_API(JSBool)
        2455                 : JS_IsInSuspendedRequest(JSRuntime *rt);
        2456                 :
        2457                 : #ifdef __cplusplus
        2458                 : JS_END_EXTERN_C
        2459                 :
        2460                 : inline bool
        2461       166188730 : IsPoisonedId(jsid iden)
        2462                 : {
        2463       166188730 :     if (JSID_IS_STRING(iden))
        2464       154089052 :         return JS::IsPoisonedPtr(JSID_TO_STRING(iden));
        2465        12099678 :     if (JSID_IS_OBJECT(iden))
        2466             274 :         return JS::IsPoisonedPtr(JSID_TO_OBJECT(iden));
        2467        12099404 :     return false;
        2468                 : }
        2469                 :
        2470                 : class JSAutoRequest {
        2471                 :   public:
        2472           18667 :     JSAutoRequest(JSContext *cx JS_GUARD_OBJECT_NOTIFIER_PARAM)
        2473           18667 :         : mContext(cx), mSaveDepth(0) {
        2474           18667 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        2475           18667 :         JS_BeginRequest(mContext);
        2476           18667 :     }
        2477           37334 :     ~JSAutoRequest() {
        2478           18667 :         JS_EndRequest(mContext);
        2479           18667 :     }
        2480                 :
        2481                 :     void suspend() {
        2482                 :         mSaveDepth = JS_SuspendRequest(mContext);
        2483                 :     }
        2484                 :     void resume() {
        2485                 :         JS_ResumeRequest(mContext, mSaveDepth);
        2486                 :     }
        2487                 :
        2488                 :   protected:
        2489                 :     JSContext *mContext;
        2490                 :     unsigned  mSaveDepth;
        2491                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        2492                 :
        2493                 : #if 0
        2494                 :   private:
        2495                 :     static void *operator new(size_t) CPP_THROW_NEW { return 0; };
        2496                 :     static void operator delete(void *, size_t) { };
        2497                 : #endif
        2498                 : };
        2499                 :
        2500                 : class JSAutoSuspendRequest {
        2501                 :   public:
        2502               0 :     JSAutoSuspendRequest(JSContext *cx JS_GUARD_OBJECT_NOTIFIER_PARAM)
        2503               0 :         : mContext(cx), mSaveDepth(0) {
        2504               0 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        2505               0 :         if (mContext) {
        2506               0 :             mSaveDepth = JS_SuspendRequest(mContext);
        2507                 :         }
        2508               0 :     }
        2509               0 :     ~JSAutoSuspendRequest() {
        2510               0 :         resume();
        2511               0 :     }
        2512                 :
        2513               0 :     void resume() {
        2514               0 :         if (mContext) {
        2515               0 :             JS_ResumeRequest(mContext, mSaveDepth);
        2516               0 :             mContext = 0;
        2517                 :         }
        2518               0 :     }
        2519                 :
        2520                 :   protected:
        2521                 :     JSContext *mContext;
        2522                 :     unsigned mSaveDepth;
        2523                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        2524                 :
        2525                 : #if 0
        2526                 :   private:
        2527                 :     static void *operator new(size_t) CPP_THROW_NEW { return 0; };
        2528                 :     static void operator delete(void *, size_t) { };
        2529                 : #endif
        2530                 : };
        2531                 :
        2532                 : class JSAutoCheckRequest {
        2533                 :   public:
        2534                 :     JSAutoCheckRequest(JSContext *cx JS_GUARD_OBJECT_NOTIFIER_PARAM) {
        2535                 : #if defined JS_THREADSAFE && defined DEBUG
        2536                 :         mContext = cx;
        2537                 :         JS_ASSERT(JS_IsInRequest(JS_GetRuntime(cx)));
        2538                 : #endif
        2539                 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        2540                 :     }
        2541                 :
        2542                 :     ~JSAutoCheckRequest() {
        2543                 : #if defined JS_THREADSAFE && defined DEBUG
        2544                 :         JS_ASSERT(JS_IsInRequest(JS_GetRuntime(mContext)));
        2545                 : #endif
        2546                 :     }
        2547                 :
        2548                 :
        2549                 :   private:
        2550                 : #if defined JS_THREADSAFE && defined DEBUG
        2551                 :     JSContext *mContext;
        2552                 : #endif
        2553                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        2554                 : };
        2555                 :
        2556                 : JS_BEGIN_EXTERN_C
        2557                 : #endif
        2558                 :
        2559                 : extern JS_PUBLIC_API(JSContextCallback)
        2560                 : JS_SetContextCallback(JSRuntime *rt, JSContextCallback cxCallback);
        2561                 :
        2562                 : extern JS_PUBLIC_API(JSContext *)
        2563                 : JS_NewContext(JSRuntime *rt, size_t stackChunkSize);
        2564                 :
        2565                 : extern JS_PUBLIC_API(void)
        2566                 : JS_DestroyContext(JSContext *cx);
        2567                 :
        2568                 : extern JS_PUBLIC_API(void)
        2569                 : JS_DestroyContextNoGC(JSContext *cx);
        2570                 :
        2571                 : extern JS_PUBLIC_API(void)
        2572                 : JS_DestroyContextMaybeGC(JSContext *cx);
        2573                 :
        2574                 : extern JS_PUBLIC_API(void *)
        2575                 : JS_GetContextPrivate(JSContext *cx);
        2576                 :
        2577                 : extern JS_PUBLIC_API(void)
        2578                 : JS_SetContextPrivate(JSContext *cx, void *data);
        2579                 :
        2580                 : extern JS_PUBLIC_API(void *)
        2581                 : JS_GetSecondContextPrivate(JSContext *cx);
        2582                 :
        2583                 : extern JS_PUBLIC_API(void)
        2584                 : JS_SetSecondContextPrivate(JSContext *cx, void *data);
        2585                 :
        2586                 : extern JS_PUBLIC_API(JSRuntime *)
        2587                 : JS_GetRuntime(JSContext *cx);
        2588                 :
        2589                 : extern JS_PUBLIC_API(JSContext *)
        2590                 : JS_ContextIterator(JSRuntime *rt, JSContext **iterp);
        2591                 :
        2592                 : extern JS_PUBLIC_API(JSVersion)
        2593                 : JS_GetVersion(JSContext *cx);
        2594                 :
        2595                 : extern JS_PUBLIC_API(JSVersion)
        2596                 : JS_SetVersion(JSContext *cx, JSVersion version);
        2597                 :
        2598                 : extern JS_PUBLIC_API(const char *)
        2599                 : JS_VersionToString(JSVersion version);
        2600                 :
        2601                 : extern JS_PUBLIC_API(JSVersion)
        2602                 : JS_StringToVersion(const char *string);
        2603                 :
        2604                 : /*
        2605                 :  * JS options are orthogonal to version, and may be freely composed with one
        2606                 :  * another as well as with version.
        2607                 :  *
        2608                 :  * JSOPTION_VAROBJFIX is recommended -- see the comments associated with the
        2609                 :  * prototypes for JS_ExecuteScript, JS_EvaluateScript, etc.
        2610                 :  */
        2611                 : #define JSOPTION_STRICT         JS_BIT(0)       /* warn on dubious practice */
        2612                 : #define JSOPTION_WERROR         JS_BIT(1)       /* convert warning to error */
        2613                 : #define JSOPTION_VAROBJFIX      JS_BIT(2)       /* make JS_EvaluateScript use
        2614                 :                                                    the last object on its 'obj'
        2615                 :                                                    param's scope chain as the
        2616                 :                                                    ECMA 'variables object' */
        2617                 : #define JSOPTION_PRIVATE_IS_NSISUPPORTS \
        2618                 :                                 JS_BIT(3)       /* context private data points
        2619                 :                                                    to an nsISupports subclass */
        2620                 : #define JSOPTION_COMPILE_N_GO   JS_BIT(4)       /* caller of JS_Compile*Script
        2621                 :                                                    promises to execute compiled
        2622                 :                                                    script once only; enables
        2623                 :                                                    compile-time scope chain
        2624                 :                                                    resolution of consts. */
        2625                 : #define JSOPTION_ATLINE         JS_BIT(5)       /* //@line number ["filename"]
        2626                 :                                                    option supported for the
        2627                 :                                                    XUL preprocessor and kindred
        2628                 :                                                    beasts. */
        2629                 : #define JSOPTION_XML            JS_BIT(6)       /* EMCAScript for XML support:
        2630                 :                                                    parse <!-- --> as a token,
        2631                 :                                                    not backward compatible with
        2632                 :                                                    the comment-hiding hack used
        2633                 :                                                    in HTML script tags. */
        2634                 : #define JSOPTION_DONT_REPORT_UNCAUGHT \
        2635                 :                                 JS_BIT(8)       /* When returning from the
        2636                 :                                                    outermost API call, prevent
        2637                 :                                                    uncaught exceptions from
        2638                 :                                                    being converted to error
        2639                 :                                                    reports */
        2640                 :
        2641                 : #define JSOPTION_RELIMIT        JS_BIT(9)       /* Throw exception on any
        2642                 :                                                    regular expression which
        2643                 :                                                    backtracks more than n^3
        2644                 :                                                    times, where n is length
        2645                 :                                                    of the input string */
        2646                 : /* JS_BIT(10) is currently unused. */
        2647                 :
        2648                 : /* JS_BIT(11) is currently unused. */
        2649                 :
        2650                 : #define JSOPTION_NO_SCRIPT_RVAL JS_BIT(12)      /* A promise to the compiler
        2651                 :                                                    that a null rval out-param
        2652                 :                                                    will be passed to each call
        2653                 :                                                    to JS_ExecuteScript. */
        2654                 : #define JSOPTION_UNROOTED_GLOBAL JS_BIT(13)     /* The GC will not root the
        2655                 :                                                    contexts' global objects
        2656                 :                                                    (see JS_GetGlobalObject),
        2657                 :                                                    leaving that up to the
        2658                 :                                                    embedding. */
        2659                 :
        2660                 : #define JSOPTION_METHODJIT      JS_BIT(14)      /* Whole-method JIT. */
        2661                 :
        2662                 : /* JS_BIT(15) is currently unused. */
        2663                 :
        2664                 : #define JSOPTION_METHODJIT_ALWAYS \
        2665                 :                                 JS_BIT(16)      /* Always whole-method JIT,
        2666                 :                                                    don't tune at run-time. */
        2667                 : #define JSOPTION_PCCOUNT        JS_BIT(17)      /* Collect per-op execution counts */
        2668                 :
        2669                 : #define JSOPTION_TYPE_INFERENCE JS_BIT(18)      /* Perform type inference. */
        2670                 :
        2671                 : /* Options which reflect compile-time properties of scripts. */
        2672                 : #define JSCOMPILEOPTION_MASK    (JSOPTION_XML)
        2673                 :
        2674                 : #define JSRUNOPTION_MASK        (JS_BITMASK(19) & ~JSCOMPILEOPTION_MASK)
        2675                 : #define JSALLOPTION_MASK        (JSCOMPILEOPTION_MASK | JSRUNOPTION_MASK)
        2676                 :
        2677                 : extern JS_PUBLIC_API(uint32_t)
        2678                 : JS_GetOptions(JSContext *cx);
        2679                 :
        2680                 : extern JS_PUBLIC_API(uint32_t)
        2681                 : JS_SetOptions(JSContext *cx, uint32_t options);
        2682                 :
        2683                 : extern JS_PUBLIC_API(uint32_t)
        2684                 : JS_ToggleOptions(JSContext *cx, uint32_t options);
        2685                 :
        2686                 : extern JS_PUBLIC_API(void)
        2687                 : JS_SetJitHardening(JSRuntime *rt, JSBool enabled);
        2688                 :
        2689                 : extern JS_PUBLIC_API(const char *)
        2690                 : JS_GetImplementationVersion(void);
        2691                 :
        2692                 : extern JS_PUBLIC_API(void)
        2693                 : JS_SetDestroyCompartmentCallback(JSRuntime *rt, JSDestroyCompartmentCallback callback);
        2694                 :
        2695                 : extern JS_PUBLIC_API(JSWrapObjectCallback)
        2696                 : JS_SetWrapObjectCallbacks(JSRuntime *rt,
        2697                 :                           JSWrapObjectCallback callback,
        2698                 :                           JSPreWrapCallback precallback);
        2699                 :
        2700                 : extern JS_PUBLIC_API(JSCrossCompartmentCall *)
        2701                 : JS_EnterCrossCompartmentCall(JSContext *cx, JSObject *target);
        2702                 :
        2703                 : extern JS_PUBLIC_API(void)
        2704                 : JS_LeaveCrossCompartmentCall(JSCrossCompartmentCall *call);
        2705                 :
        2706                 : extern JS_PUBLIC_API(void)
        2707                 : JS_SetCompartmentPrivate(JSCompartment *compartment, void *data);
        2708                 :
        2709                 : extern JS_PUBLIC_API(void *)
        2710                 : JS_GetCompartmentPrivate(JSCompartment *compartment);
        2711                 :
        2712                 : extern JS_PUBLIC_API(JSBool)
        2713                 : JS_WrapObject(JSContext *cx, JSObject **objp);
        2714                 :
        2715                 : extern JS_PUBLIC_API(JSBool)
        2716                 : JS_WrapValue(JSContext *cx, jsval *vp);
        2717                 :
        2718                 : extern JS_PUBLIC_API(JSObject *)
        2719                 : JS_TransplantObject(JSContext *cx, JSObject *origobj, JSObject *target);
        2720                 :
        2721                 : extern JS_FRIEND_API(JSObject *)
        2722                 : js_TransplantObjectWithWrapper(JSContext *cx,
        2723                 :                                JSObject *origobj,
        2724                 :                                JSObject *origwrapper,
        2725                 :                                JSObject *targetobj,
        2726                 :                                JSObject *targetwrapper);
        2727                 :
        2728                 : extern JS_FRIEND_API(JSObject *)
        2729                 : js_TransplantObjectWithWrapper(JSContext *cx,
        2730                 :                                JSObject *origobj,
        2731                 :                                JSObject *origwrapper,
        2732                 :                                JSObject *targetobj,
        2733                 :                                JSObject *targetwrapper);
        2734                 :
        2735                 : #ifdef __cplusplus
        2736                 : JS_END_EXTERN_C
        2737                 :
        2738                 : namespace js {
        2739                 : class AutoCompartment;
        2740                 : }
        2741                 :
        2742                 : class JS_PUBLIC_API(JSAutoEnterCompartment)
        2743                 : {
        2744                 :     /*
        2745                 :      * This is a poor man's Maybe<AutoCompartment>, because we don't have
        2746                 :      * access to the AutoCompartment definition here.  We statically assert in
        2747                 :      * jsapi.cpp that we have the right size here.
        2748                 :      *
        2749                 :      * In practice, 32-bit Windows and Android get 16-word |bytes|, while
        2750                 :      * other platforms get 13-word |bytes|.
        2751                 :      */
        2752                 :     void* bytes[sizeof(void*) == 4 && MOZ_ALIGNOF(uint64_t) == 8 ? 16 : 13];
        2753                 :
        2754                 :   protected:
        2755           25040 :     js::AutoCompartment *getAutoCompartment() {
        2756           25040 :         JS_ASSERT(state == STATE_OTHER_COMPARTMENT);
        2757           25040 :         return reinterpret_cast<js::AutoCompartment*>(bytes);
        2758                 :     }
        2759                 :
        2760                 :     /*
        2761                 :      * This object may be in one of three states.  If enter() or
        2762                 :      * enterAndIgnoreErrors() hasn't been called, it's in STATE_UNENTERED.
        2763                 :      * Otherwise, if we were asked to enter into the current compartment, our
        2764                 :      * state is STATE_SAME_COMPARTMENT.  If we actually created an
        2765                 :      * AutoCompartment and entered another compartment, our state is
        2766                 :      * STATE_OTHER_COMPARTMENT.
        2767                 :      */
        2768                 :     enum State {
        2769                 :         STATE_UNENTERED,
        2770                 :         STATE_SAME_COMPARTMENT,
        2771                 :         STATE_OTHER_COMPARTMENT
        2772                 :     } state;
        2773                 :
        2774                 :   public:
        2775           44867 :     JSAutoEnterCompartment() : state(STATE_UNENTERED) {}
        2776                 :
        2777                 :     bool enter(JSContext *cx, JSObject *target);
        2778                 :
        2779                 :     void enterAndIgnoreErrors(JSContext *cx, JSObject *target);
        2780                 :
        2781                 :     bool entered() const { return state != STATE_UNENTERED; }
        2782                 :
        2783                 :     ~JSAutoEnterCompartment();
        2784                 : };
        2785                 :
        2786                 : JS_BEGIN_EXTERN_C
        2787                 : #endif
        2788                 :
        2789                 : typedef void (*JSIterateCompartmentCallback)(JSRuntime *rt, void *data, JSCompartment *compartment);
        2790                 :
        2791                 : /*
        2792                 :  * This function calls |compartmentCallback| on every compartment.  Beware that
        2793                 :  * there is no guarantee that the compartment will survive after the callback
        2794                 :  * returns.
        2795                 :  */
        2796                 : extern JS_PUBLIC_API(void)
        2797                 : JS_IterateCompartments(JSRuntime *rt, void *data,
        2798                 :                        JSIterateCompartmentCallback compartmentCallback);
        2799                 :
        2800                 : extern JS_PUBLIC_API(JSObject *)
        2801                 : JS_GetGlobalObject(JSContext *cx);
        2802                 :
        2803                 : extern JS_PUBLIC_API(void)
        2804                 : JS_SetGlobalObject(JSContext *cx, JSObject *obj);
        2805                 :
        2806                 : /*
        2807                 :  * Initialize standard JS class constructors, prototypes, and any top-level
        2808                 :  * functions and constants associated with the standard classes (e.g. isNaN
        2809                 :  * for Number).
        2810                 :  *
        2811                 :  * NB: This sets cx's global object to obj if it was null.
        2812                 :  */
        2813                 : extern JS_PUBLIC_API(JSBool)
        2814                 : JS_InitStandardClasses(JSContext *cx, JSObject *obj);
        2815                 :
        2816                 : /*
        2817                 :  * Resolve id, which must contain either a string or an int, to a standard
        2818                 :  * class name in obj if possible, defining the class's constructor and/or
        2819                 :  * prototype and storing true in *resolved.  If id does not name a standard
        2820                 :  * class or a top-level property induced by initializing a standard class,
        2821                 :  * store false in *resolved and just return true.  Return false on error,
        2822                 :  * as usual for JSBool result-typed API entry points.
        2823                 :  *
        2824                 :  * This API can be called directly from a global object class's resolve op,
        2825                 :  * to define standard classes lazily.  The class's enumerate op should call
        2826                 :  * JS_EnumerateStandardClasses(cx, obj), to define eagerly during for..in
        2827                 :  * loops any classes not yet resolved lazily.
        2828                 :  */
        2829                 : extern JS_PUBLIC_API(JSBool)
        2830                 : JS_ResolveStandardClass(JSContext *cx, JSObject *obj, jsid id,
        2831                 :                         JSBool *resolved);
        2832                 :
        2833                 : extern JS_PUBLIC_API(JSBool)
        2834                 : JS_EnumerateStandardClasses(JSContext *cx, JSObject *obj);
        2835                 :
        2836                 : /*
        2837                 :  * Enumerate any already-resolved standard class ids into ida, or into a new
        2838                 :  * JSIdArray if ida is null.  Return the augmented array on success, null on
        2839                 :  * failure with ida (if it was non-null on entry) destroyed.
        2840                 :  */
        2841                 : extern JS_PUBLIC_API(JSIdArray *)
        2842                 : JS_EnumerateResolvedStandardClasses(JSContext *cx, JSObject *obj,
        2843                 :                                     JSIdArray *ida);
        2844                 :
        2845                 : extern JS_PUBLIC_API(JSBool)
        2846                 : JS_GetClassObject(JSContext *cx, JSObject *obj, JSProtoKey key,
        2847                 :                   JSObject **objp);
        2848                 :
        2849                 : /*
        2850                 :  * Returns the original value of |Function.prototype| from the global object in
        2851                 :  * which |forObj| was created.
        2852                 :  */
        2853                 : extern JS_PUBLIC_API(JSObject *)
        2854                 : JS_GetFunctionPrototype(JSContext *cx, JSObject *forObj);
        2855                 :
        2856                 : /*
        2857                 :  * Returns the original value of |Object.prototype| from the global object in
        2858                 :  * which |forObj| was created.
        2859                 :  */
        2860                 : extern JS_PUBLIC_API(JSObject *)
        2861                 : JS_GetObjectPrototype(JSContext *cx, JSObject *forObj);
        2862                 :
        2863                 : extern JS_PUBLIC_API(JSObject *)
        2864                 : JS_GetGlobalForObject(JSContext *cx, JSObject *obj);
        2865                 :
        2866                 : extern JS_PUBLIC_API(JSObject *)
        2867                 : JS_GetGlobalForScopeChain(JSContext *cx);
        2868                 :
        2869                 : /*
        2870                 :  * Initialize the 'Reflect' object on a global object.
        2871                 :  */
        2872                 : extern JS_PUBLIC_API(JSObject *)
        2873                 : JS_InitReflect(JSContext *cx, JSObject *global);
        2874                 :
        2875                 : #ifdef JS_HAS_CTYPES
        2876                 : /*
        2877                 :  * Initialize the 'ctypes' object on a global variable 'obj'. The 'ctypes'
        2878                 :  * object will be sealed.
        2879                 :  */
        2880                 : extern JS_PUBLIC_API(JSBool)
        2881                 : JS_InitCTypesClass(JSContext *cx, JSObject *global);
        2882                 :
        2883                 : /*
        2884                 :  * Convert a unicode string 'source' of length 'slen' to the platform native
        2885                 :  * charset, returning a null-terminated string allocated with JS_malloc. On
        2886                 :  * failure, this function should report an error.
        2887                 :  */
        2888                 : typedef char *
        2889                 : (* JSCTypesUnicodeToNativeFun)(JSContext *cx, const jschar *source, size_t slen);
        2890                 :
        2891                 : /*
        2892                 :  * Set of function pointers that ctypes can use for various internal functions.
        2893                 :  * See JS_SetCTypesCallbacks below. Providing NULL for a function is safe,
        2894                 :  * and will result in the applicable ctypes functionality not being available.
        2895                 :  */
        2896                 : struct JSCTypesCallbacks {
        2897                 :     JSCTypesUnicodeToNativeFun unicodeToNative;
        2898                 : };
        2899                 :
        2900                 : typedef struct JSCTypesCallbacks JSCTypesCallbacks;
        2901                 :
        2902                 : /*
        2903                 :  * Set the callbacks on the provided 'ctypesObj' object. 'callbacks' should be a
        2904                 :  * pointer to static data that exists for the lifetime of 'ctypesObj', but it
        2905                 :  * may safely be altered after calling this function and without having
        2906                 :  * to call this function again.
        2907                 :  */
        2908                 : extern JS_PUBLIC_API(void)
        2909                 : JS_SetCTypesCallbacks(JSObject *ctypesObj, JSCTypesCallbacks *callbacks);
        2910                 : #endif
        2911                 :
        2912                 : typedef JSBool
        2913                 : (* JSEnumerateDiagnosticMemoryCallback)(void *ptr, size_t length);
        2914                 :
        2915                 : /*
        2916                 :  * Enumerate memory regions that contain diagnostic information
        2917                 :  * intended to be included in crash report minidumps.
        2918                 :  */
        2919                 : extern JS_PUBLIC_API(void)
        2920                 : JS_EnumerateDiagnosticMemoryRegions(JSEnumerateDiagnosticMemoryCallback callback);
        2921                 :
        2922                 : /*
        2923                 :  * Macros to hide interpreter stack layout details from a JSFastNative using
        2924                 :  * its jsval *vp parameter. The stack layout underlying invocation can't change
        2925                 :  * without breaking source and binary compatibility (argv[-2] is well-known to
        2926                 :  * be the callee jsval, and argv[-1] is as well known to be |this|).
        2927                 :  *
        2928                 :  * Note well: However, argv[-1] may be JSVAL_NULL where with slow natives it
        2929                 :  * is the global object, so embeddings implementing fast natives *must* call
        2930                 :  * JS_THIS or JS_THIS_OBJECT and test for failure indicated by a null return,
        2931                 :  * which should propagate as a false return from native functions and hooks.
        2932                 :  *
        2933                 :  * To reduce boilerplace checks, JS_InstanceOf and JS_GetInstancePrivate now
        2934                 :  * handle a null obj parameter by returning false (throwing a TypeError if
        2935                 :  * given non-null argv), so most native functions that type-check their |this|
        2936                 :  * parameter need not add null checking.
        2937                 :  *
        2938                 :  * NB: there is an anti-dependency between JS_CALLEE and JS_SET_RVAL: native
        2939                 :  * methods that may inspect their callee must defer setting their return value
        2940                 :  * until after any such possible inspection. Otherwise the return value will be
        2941                 :  * inspected instead of the callee function object.
        2942                 :  *
        2943                 :  * WARNING: These are not (yet) mandatory macros, but new code outside of the
        2944                 :  * engine should use them. In the Mozilla 2.0 milestone their definitions may
        2945                 :  * change incompatibly.
        2946                 :  *
        2947                 :  * N.B. constructors must not use JS_THIS, as no 'this' object has been created.
        2948                 :  */
        2949                 :
        2950                 : #define JS_CALLEE(cx,vp)        ((vp)[0])
        2951                 : #define JS_THIS(cx,vp)          JS_ComputeThis(cx, vp)
        2952                 : #define JS_THIS_OBJECT(cx,vp)   (JSVAL_TO_OBJECT(JS_THIS(cx,vp)))
        2953                 : #define JS_ARGV(cx,vp)          ((vp) + 2)
        2954                 : #define JS_RVAL(cx,vp)          (*(vp))
        2955                 : #define JS_SET_RVAL(cx,vp,v)    (*(vp) = (v))
        2956                 :
        2957                 : extern JS_PUBLIC_API(jsval)
        2958                 : JS_ComputeThis(JSContext *cx, jsval *vp);
        2959                 :
        2960                 : #ifdef __cplusplus
        2961                 : #undef JS_THIS
        2962                 : static inline jsval
        2963            1278 : JS_THIS(JSContext *cx, jsval *vp)
        2964                 : {
        2965            1278 :     return JSVAL_IS_PRIMITIVE(vp[1]) ? JS_ComputeThis(cx, vp) : vp[1];
        2966                 : }
        2967                 : #endif
        2968                 :
        2969                 : /*
        2970                 :  * |this| is passed to functions in ES5 without change.  Functions themselves
        2971                 :  * do any post-processing they desire to box |this|, compute the global object,
        2972                 :  * &c.  Use this macro to retrieve a function's unboxed |this| value.
        2973                 :  *
        2974                 :  * This macro must not be used in conjunction with JS_THIS or JS_THIS_OBJECT,
        2975                 :  * or vice versa.  Either use the provided this value with this macro, or
        2976                 :  * compute the boxed this value using those.
        2977                 :  *
        2978                 :  * N.B. constructors must not use JS_THIS_VALUE, as no 'this' object has been
        2979                 :  * created.
        2980                 :  */
        2981                 : #define JS_THIS_VALUE(cx,vp)    ((vp)[1])
        2982                 :
        2983                 : extern JS_PUBLIC_API(void)
        2984                 : JS_MallocInCompartment(JSCompartment *comp, size_t nbytes);
        2985                 :
        2986                 : extern JS_PUBLIC_API(void)
        2987                 : JS_FreeInCompartment(JSCompartment *comp, size_t nbytes);
        2988                 :
        2989                 : extern JS_PUBLIC_API(void *)
        2990                 : JS_malloc(JSContext *cx, size_t nbytes);
        2991                 :
        2992                 : extern JS_PUBLIC_API(void *)
        2993                 : JS_realloc(JSContext *cx, void *p, size_t nbytes);
        2994                 :
        2995                 : /*
        2996                 :  * A wrapper for js_free(p) that may delay js_free(p) invocation as a
        2997                 :  * performance optimization.
        2998                 :  */
        2999                 : extern JS_PUBLIC_API(void)
        3000                 : JS_free(JSContext *cx, void *p);
        3001                 :
        3002                 : /*
        3003                 :  * A wrapper for js_free(p) that may delay js_free(p) invocation as a
        3004                 :  * performance optimization as specified by the given JSFreeOp instance.
        3005                 :  */
        3006                 : extern JS_PUBLIC_API(void)
        3007                 : JS_freeop(JSFreeOp *fop, void *p);
        3008                 :
        3009                 : extern JS_PUBLIC_API(JSFreeOp *)
        3010                 : JS_GetDefaultFreeOp(JSRuntime *rt);
        3011                 :
        3012                 : extern JS_PUBLIC_API(void)
        3013                 : JS_updateMallocCounter(JSContext *cx, size_t nbytes);
        3014                 :
        3015                 : extern JS_PUBLIC_API(char *)
        3016                 : JS_strdup(JSContext *cx, const char *s);
        3017                 :
        3018                 : extern JS_PUBLIC_API(JSBool)
        3019                 : JS_NewNumberValue(JSContext *cx, double d, jsval *rval);
        3020                 :
        3021                 : /*
        3022                 :  * A GC root is a pointer to a jsval, JSObject * or JSString * that itself
        3023                 :  * points into the GC heap. JS_AddValueRoot takes a pointer to a jsval and
        3024                 :  * JS_AddGCThingRoot takes a pointer to a JSObject * or JString *.
        3025                 :  *
        3026                 :  * Note that, since JS_Add*Root stores the address of a variable (of type
        3027                 :  * jsval, JSString *, or JSObject *), that variable must live until
        3028                 :  * JS_Remove*Root is called to remove that variable. For example, after:
        3029                 :  *
        3030                 :  *   void some_function() {
        3031                 :  *     jsval v;
        3032                 :  *     JS_AddNamedRootedValue(cx, &v, "name");
        3033                 :  *
        3034                 :  * the caller must perform
        3035                 :  *
        3036                 :  *     JS_RemoveRootedValue(cx, &v);
        3037                 :  *
        3038                 :  * before some_function() returns.
        3039                 :  *
        3040                 :  * Also, use JS_AddNamed*Root(cx, &structPtr->memberObj, "structPtr->memberObj")
        3041                 :  * in preference to JS_Add*Root(cx, &structPtr->memberObj), in order to identify
        3042                 :  * roots by their source callsites.  This way, you can find the callsite while
        3043                 :  * debugging if you should fail to do JS_Remove*Root(cx, &structPtr->memberObj)
        3044                 :  * before freeing structPtr's memory.
        3045                 :  */
        3046                 : extern JS_PUBLIC_API(JSBool)
        3047                 : JS_AddValueRoot(JSContext *cx, jsval *vp);
        3048                 :
        3049                 : extern JS_PUBLIC_API(JSBool)
        3050                 : JS_AddStringRoot(JSContext *cx, JSString **rp);
        3051                 :
        3052                 : extern JS_PUBLIC_API(JSBool)
        3053                 : JS_AddObjectRoot(JSContext *cx, JSObject **rp);
        3054                 :
        3055                 : extern JS_PUBLIC_API(JSBool)
        3056                 : JS_AddGCThingRoot(JSContext *cx, void **rp);
        3057                 :
        3058                 : #ifdef NAME_ALL_GC_ROOTS
        3059                 : #define JS_DEFINE_TO_TOKEN(def) #def
        3060                 : #define JS_DEFINE_TO_STRING(def) JS_DEFINE_TO_TOKEN(def)
        3061                 : #define JS_AddValueRoot(cx,vp) JS_AddNamedValueRoot((cx), (vp), (__FILE__ ":" JS_TOKEN_TO_STRING(__LINE__))
        3062                 : #define JS_AddStringRoot(cx,rp) JS_AddNamedStringRoot((cx), (rp), (__FILE__ ":" JS_TOKEN_TO_STRING(__LINE__))
        3063                 : #define JS_AddObjectRoot(cx,rp) JS_AddNamedObjectRoot((cx), (rp), (__FILE__ ":" JS_TOKEN_TO_STRING(__LINE__))
        3064                 : #define JS_AddGCThingRoot(cx,rp) JS_AddNamedGCThingRoot((cx), (rp), (__FILE__ ":" JS_TOKEN_TO_STRING(__LINE__))
        3065                 : #endif
        3066                 :
        3067                 : extern JS_PUBLIC_API(JSBool)
        3068                 : JS_AddNamedValueRoot(JSContext *cx, jsval *vp, const char *name);
        3069                 :
        3070                 : extern JS_PUBLIC_API(JSBool)
        3071                 : JS_AddNamedStringRoot(JSContext *cx, JSString **rp, const char *name);
        3072                 :
        3073                 : extern JS_PUBLIC_API(JSBool)
        3074                 : JS_AddNamedObjectRoot(JSContext *cx, JSObject **rp, const char *name);
        3075                 :
        3076                 : extern JS_PUBLIC_API(JSBool)
        3077                 : JS_AddNamedScriptRoot(JSContext *cx, JSScript **rp, const char *name);
        3078                 :
        3079                 : extern JS_PUBLIC_API(JSBool)
        3080                 : JS_AddNamedGCThingRoot(JSContext *cx, void **rp, const char *name);
        3081                 :
        3082                 : extern JS_PUBLIC_API(void)
        3083                 : JS_RemoveValueRoot(JSContext *cx, jsval *vp);
        3084                 :
        3085                 : extern JS_PUBLIC_API(void)
        3086                 : JS_RemoveStringRoot(JSContext *cx, JSString **rp);
        3087                 :
        3088                 : extern JS_PUBLIC_API(void)
        3089                 : JS_RemoveObjectRoot(JSContext *cx, JSObject **rp);
        3090                 :
        3091                 : extern JS_PUBLIC_API(void)
        3092                 : JS_RemoveScriptRoot(JSContext *cx, JSScript **rp);
        3093                 :
        3094                 : extern JS_PUBLIC_API(void)
        3095                 : JS_RemoveGCThingRoot(JSContext *cx, void **rp);
        3096                 :
        3097                 : extern JS_PUBLIC_API(void)
        3098                 : JS_RemoveValueRootRT(JSRuntime *rt, jsval *vp);
        3099                 :
        3100                 : extern JS_PUBLIC_API(void)
        3101                 : JS_RemoveStringRootRT(JSRuntime *rt, JSString **rp);
        3102                 :
        3103                 : extern JS_PUBLIC_API(void)
        3104                 : JS_RemoveObjectRootRT(JSRuntime *rt, JSObject **rp);
        3105                 :
        3106                 : extern JS_PUBLIC_API(void)
        3107                 : JS_RemoveScriptRootRT(JSRuntime *rt, JSScript **rp);
        3108                 :
        3109                 : /* TODO: remove these APIs */
        3110                 :
        3111                 : extern JS_FRIEND_API(JSBool)
        3112                 : js_AddRootRT(JSRuntime *rt, jsval *vp, const char *name);
        3113                 :
        3114                 : extern JS_FRIEND_API(JSBool)
        3115                 : js_AddGCThingRootRT(JSRuntime *rt, void **rp, const char *name);
        3116                 :
        3117                 : extern JS_FRIEND_API(void)
        3118                 : js_RemoveRoot(JSRuntime *rt, void *rp);
        3119                 :
        3120                 : /*
        3121                 :  * C-compatible version of the Anchor class. It should be called after the last
        3122                 :  * use of the variable it protects.
        3123                 :  */
        3124                 : extern JS_NEVER_INLINE JS_PUBLIC_API(void)
        3125                 : JS_AnchorPtr(void *p);
        3126                 :
        3127                 : /*
        3128                 :  * This symbol may be used by embedders to detect the change from the old
        3129                 :  * JS_AddRoot(JSContext *, void *) APIs to the new ones above.
        3130                 :  */
        3131                 : #define JS_TYPED_ROOTING_API
        3132                 :
        3133                 : /* Obsolete rooting APIs. */
        3134                 : #define JS_EnterLocalRootScope(cx) (JS_TRUE)
        3135                 : #define JS_LeaveLocalRootScope(cx) ((void) 0)
        3136                 : #define JS_LeaveLocalRootScopeWithResult(cx, rval) ((void) 0)
        3137                 : #define JS_ForgetLocalRoot(cx, thing) ((void) 0)
        3138                 :
        3139                 : typedef enum JSGCRootType {
        3140                 :     JS_GC_ROOT_VALUE_PTR,
        3141                 :     JS_GC_ROOT_GCTHING_PTR
        3142                 : } JSGCRootType;
        3143                 :
        3144                 : #ifdef DEBUG
        3145                 : extern JS_PUBLIC_API(void)
        3146                 : JS_DumpNamedRoots(JSRuntime *rt,
        3147                 :                   void (*dump)(const char *name, void *rp, JSGCRootType type, void *data),
        3148                 :                   void *data);
        3149                 : #endif
        3150                 :
        3151                 : /*
        3152                 :  * Call JS_MapGCRoots to map the GC's roots table using map(rp, name, data).
        3153                 :  * The root is pointed at by rp; if the root is unnamed, name is null; data is
        3154                 :  * supplied from the third parameter to JS_MapGCRoots.
        3155                 :  *
        3156                 :  * The map function should return JS_MAP_GCROOT_REMOVE to cause the currently
        3157                 :  * enumerated root to be removed.  To stop enumeration, set JS_MAP_GCROOT_STOP
        3158                 :  * in the return value.  To keep on mapping, return JS_MAP_GCROOT_NEXT.  These
        3159                 :  * constants are flags; you can OR them together.
        3160                 :  *
        3161                 :  * This function acquires and releases rt's GC lock around the mapping of the
        3162                 :  * roots table, so the map function should run to completion in as few cycles
        3163                 :  * as possible.  Of course, map cannot call JS_GC, JS_MaybeGC, JS_BeginRequest,
        3164                 :  * or any JS API entry point that acquires locks, without double-tripping or
        3165                 :  * deadlocking on the GC lock.
        3166                 :  *
        3167                 :  * The JSGCRootType parameter indicates whether rp is a pointer to a Value
        3168                 :  * (which is obtained by '(Value *)rp') or a pointer to a GC-thing pointer
        3169                 :  * (which is obtained by '(void **)rp').
        3170                 :  *
        3171                 :  * JS_MapGCRoots returns the count of roots that were successfully mapped.
        3172                 :  */
        3173                 : #define JS_MAP_GCROOT_NEXT      0       /* continue mapping entries */
        3174                 : #define JS_MAP_GCROOT_STOP      1       /* stop mapping entries */
        3175                 : #define JS_MAP_GCROOT_REMOVE    2       /* remove and free the current entry */
        3176                 :
        3177                 : typedef int
        3178                 : (* JSGCRootMapFun)(void *rp, JSGCRootType type, const char *name, void *data);
        3179                 :
        3180                 : extern JS_PUBLIC_API(uint32_t)
        3181                 : JS_MapGCRoots(JSRuntime *rt, JSGCRootMapFun map, void *data);
        3182                 :
        3183                 : extern JS_PUBLIC_API(JSBool)
        3184                 : JS_LockGCThing(JSContext *cx, void *thing);
        3185                 :
        3186                 : extern JS_PUBLIC_API(JSBool)
        3187                 : JS_LockGCThingRT(JSRuntime *rt, void *thing);
        3188                 :
        3189                 : extern JS_PUBLIC_API(JSBool)
        3190                 : JS_UnlockGCThing(JSContext *cx, void *thing);
        3191                 :
        3192                 : extern JS_PUBLIC_API(JSBool)
        3193                 : JS_UnlockGCThingRT(JSRuntime *rt, void *thing);
        3194                 :
        3195                 : /*
        3196                 :  * Register externally maintained GC roots.
        3197                 :  *
        3198                 :  * traceOp: the trace operation. For each root the implementation should call
        3199                 :  *          JS_CallTracer whenever the root contains a traceable thing.
        3200                 :  * data:    the data argument to pass to each invocation of traceOp.
        3201                 :  */
        3202                 : extern JS_PUBLIC_API(void)
        3203                 : JS_SetExtraGCRootsTracer(JSRuntime *rt, JSTraceDataOp traceOp, void *data);
        3204                 :
        3205                 : /*
        3206                 :  * JS_CallTracer API and related macros for implementors of JSTraceOp, to
        3207                 :  * enumerate all references to traceable things reachable via a property or
        3208                 :  * other strong ref identified for debugging purposes by name or index or
        3209                 :  * a naming callback.
        3210                 :  *
        3211                 :  * See the JSTraceOp typedef.
        3212                 :  */
        3213                 :
        3214                 : /*
        3215                 :  * Use the following macros to check if a particular jsval is a traceable
        3216                 :  * thing and to extract the thing and its kind to pass to JS_CallTracer.
        3217                 :  */
        3218                 : static JS_ALWAYS_INLINE JSBool
        3219               0 : JSVAL_IS_TRACEABLE(jsval v)
        3220                 : {
        3221               0 :     return JSVAL_IS_TRACEABLE_IMPL(JSVAL_TO_IMPL(v));
        3222                 : }
        3223                 :
        3224                 : static JS_ALWAYS_INLINE void *
        3225               0 : JSVAL_TO_TRACEABLE(jsval v)
        3226                 : {
        3227               0 :     return JSVAL_TO_GCTHING(v);
        3228                 : }
        3229                 :
        3230                 : static JS_ALWAYS_INLINE JSGCTraceKind
        3231               0 : JSVAL_TRACE_KIND(jsval v)
        3232                 : {
        3233               0 :     JS_ASSERT(JSVAL_IS_GCTHING(v));
        3234               0 :     return (JSGCTraceKind) JSVAL_TRACE_KIND_IMPL(JSVAL_TO_IMPL(v));
        3235                 : }
        3236                 :
        3237                 : /*
        3238                 :  * Tracer callback, called for each traceable thing directly referenced by a
        3239                 :  * particular object or runtime structure. It is the callback responsibility
        3240                 :  * to ensure the traversal of the full object graph via calling eventually
        3241                 :  * JS_TraceChildren on the passed thing. In this case the callback must be
        3242                 :  * prepared to deal with cycles in the traversal graph.
        3243                 :  *
        3244                 :  * kind argument is one of JSTRACE_OBJECT, JSTRACE_STRING or a tag denoting
        3245                 :  * internal implementation-specific traversal kind. In the latter case the only
        3246                 :  * operations on thing that the callback can do is to call JS_TraceChildren or
        3247                 :  * DEBUG-only JS_PrintTraceThingInfo.
        3248                 :  *
        3249                 :  * If eagerlyTraceWeakMaps is true, when we trace a WeakMap visit all
        3250                 :  * of its mappings.  This should be used in cases where the tracer
        3251                 :  * wants to use the existing liveness of entries.
        3252                 :  */
        3253                 : typedef void
        3254                 : (* JSTraceCallback)(JSTracer *trc, void **thingp, JSGCTraceKind kind);
        3255                 :
        3256           20811 : struct JSTracer {
        3257                 :     JSRuntime           *runtime;
        3258                 :     JSTraceCallback     callback;
        3259                 :     JSTraceNamePrinter  debugPrinter;
        3260                 :     const void          *debugPrintArg;
        3261                 :     size_t              debugPrintIndex;
        3262                 :     JSBool              eagerlyTraceWeakMaps;
        3263                 : };
        3264                 :
        3265                 : /*
        3266                 :  * The method to call on each reference to a traceable thing stored in a
        3267                 :  * particular JSObject or other runtime structure. With DEBUG defined the
        3268                 :  * caller before calling JS_CallTracer must initialize JSTracer fields
        3269                 :  * describing the reference using the macros below.
        3270                 :  */
        3271                 : extern JS_PUBLIC_API(void)
        3272                 : JS_CallTracer(JSTracer *trc, void *thing, JSGCTraceKind kind);
        3273                 :
        3274                 : /*
        3275                 :  * Set debugging information about a reference to a traceable thing to prepare
        3276                 :  * for the following call to JS_CallTracer.
        3277                 :  *
        3278                 :  * When printer is null, arg must be const char * or char * C string naming
        3279                 :  * the reference and index must be either (size_t)-1 indicating that the name
        3280                 :  * alone describes the reference or it must be an index into some array vector
        3281                 :  * that stores the reference.
        3282                 :  *
        3283                 :  * When printer callback is not null, the arg and index arguments are
        3284                 :  * available to the callback as debugPrintArg and debugPrintIndex fields
        3285                 :  * of JSTracer.
        3286                 :  *
        3287                 :  * The storage for name or callback's arguments needs to live only until
        3288                 :  * the following call to JS_CallTracer returns.
        3289                 :  */
        3290                 : #ifdef DEBUG
        3291                 : # define JS_SET_TRACING_DETAILS(trc, printer, arg, index)                     \
        3292                 :     JS_BEGIN_MACRO                                                            \
        3293                 :         (trc)->debugPrinter = (printer);                                      \
        3294                 :         (trc)->debugPrintArg = (arg);                                         \
        3295                 :         (trc)->debugPrintIndex = (index);                                     \
        3296                 :     JS_END_MACRO
        3297                 : #else
        3298                 : # define JS_SET_TRACING_DETAILS(trc, printer, arg, index)                     \
        3299                 :     JS_BEGIN_MACRO                                                            \
        3300                 :     JS_END_MACRO
        3301                 : #endif
        3302                 :
        3303                 : /*
        3304                 :  * Convenience macro to describe the argument of JS_CallTracer using C string
        3305                 :  * and index.
        3306                 :  */
        3307                 : # define JS_SET_TRACING_INDEX(trc, name, index)                               \
        3308                 :     JS_SET_TRACING_DETAILS(trc, NULL, name, index)
        3309                 :
        3310                 : /*
        3311                 :  * Convenience macro to describe the argument of JS_CallTracer using C string.
        3312                 :  */
        3313                 : # define JS_SET_TRACING_NAME(trc, name)                                       \
        3314                 :     JS_SET_TRACING_DETAILS(trc, NULL, name, (size_t)-1)
        3315                 :
        3316                 : /*
        3317                 :  * Convenience macro to invoke JS_CallTracer using C string as the name for
        3318                 :  * the reference to a traceable thing.
        3319                 :  */
        3320                 : # define JS_CALL_TRACER(trc, thing, kind, name)                               \
        3321                 :     JS_BEGIN_MACRO                                                            \
        3322                 :         JS_SET_TRACING_NAME(trc, name);                                       \
        3323                 :         JS_CallTracer((trc), (thing), (kind));                                \
        3324                 :     JS_END_MACRO
        3325                 :
        3326                 : /*
        3327                 :  * Convenience macros to invoke JS_CallTracer when jsval represents a
        3328                 :  * reference to a traceable thing.
        3329                 :  */
        3330                 : #define JS_CALL_VALUE_TRACER(trc, val, name)                                  \
        3331                 :     JS_BEGIN_MACRO                                                            \
        3332                 :         if (JSVAL_IS_TRACEABLE(val)) {                                        \
        3333                 :             JS_CALL_TRACER((trc), JSVAL_TO_GCTHING(val),                      \
        3334                 :                            JSVAL_TRACE_KIND(val), name);                      \
        3335                 :         }                                                                     \
        3336                 :     JS_END_MACRO
        3337                 :
        3338                 : #define JS_CALL_OBJECT_TRACER(trc, object, name)                              \
        3339                 :     JS_BEGIN_MACRO                                                            \
        3340                 :         JSObject *obj_ = (object);                                            \
        3341                 :         JS_ASSERT(obj_);                                                      \
        3342                 :         JS_CALL_TRACER((trc), obj_, JSTRACE_OBJECT, name);                    \
        3343                 :     JS_END_MACRO
        3344                 :
        3345                 : #define JS_CALL_STRING_TRACER(trc, string, name)                              \
        3346                 :     JS_BEGIN_MACRO                                                            \
        3347                 :         JSString *str_ = (string);                                            \
        3348                 :         JS_ASSERT(str_);                                                      \
        3349                 :         JS_CALL_TRACER((trc), str_, JSTRACE_STRING, name);                    \
        3350                 :     JS_END_MACRO
        3351                 :
        3352                 : /*
        3353                 :  * API for JSTraceCallback implementations.
        3354                 :  */
        3355                 : extern JS_PUBLIC_API(void)
        3356                 : JS_TracerInit(JSTracer *trc, JSRuntime *rt, JSTraceCallback callback);
        3357                 :
        3358                 : extern JS_PUBLIC_API(void)
        3359                 : JS_TraceChildren(JSTracer *trc, void *thing, JSGCTraceKind kind);
        3360                 :
        3361                 : extern JS_PUBLIC_API(void)
        3362                 : JS_TraceRuntime(JSTracer *trc);
        3363                 :
        3364                 : #ifdef DEBUG
        3365                 :
        3366                 : extern JS_PUBLIC_API(void)
        3367                 : JS_PrintTraceThingInfo(char *buf, size_t bufsize, JSTracer *trc,
        3368                 :                        void *thing, JSGCTraceKind kind, JSBool includeDetails);
        3369                 :
        3370                 : extern JS_PUBLIC_API(const char *)
        3371                 : JS_GetTraceEdgeName(JSTracer *trc, char *buffer, int bufferSize);
        3372                 :
        3373                 : /*
        3374                 :  * DEBUG-only method to dump the object graph of heap-allocated things.
        3375                 :  *
        3376                 :  * fp:              file for the dump output.
        3377                 :  * start:           when non-null, dump only things reachable from start
        3378                 :  *                  thing. Otherwise dump all things reachable from the
        3379                 :  *                  runtime roots.
        3380                 :  * startKind:       trace kind of start if start is not null. Must be
        3381                 :  *                  JSTRACE_OBJECT when start is null.
        3382                 :  * thingToFind:     dump only paths in the object graph leading to thingToFind
        3383                 :  *                  when non-null.
        3384                 :  * maxDepth:        the upper bound on the number of edges to descend from the
        3385                 :  *                  graph roots.
        3386                 :  * thingToIgnore:   thing to ignore during the graph traversal when non-null.
        3387                 :  */
        3388                 : extern JS_PUBLIC_API(JSBool)
        3389                 : JS_DumpHeap(JSRuntime *rt, FILE *fp, void* startThing, JSGCTraceKind kind,
        3390                 :             void *thingToFind, size_t maxDepth, void *thingToIgnore);
        3391                 :
        3392                 : #endif
        3393                 :
        3394                 : /*
        3395                 :  * Garbage collector API.
        3396                 :  */
        3397                 : extern JS_PUBLIC_API(void)
        3398                 : JS_GC(JSContext *cx);
        3399                 :
        3400                 : extern JS_PUBLIC_API(void)
        3401                 : JS_CompartmentGC(JSContext *cx, JSCompartment *comp);
        3402                 :
        3403                 : extern JS_PUBLIC_API(void)
        3404                 : JS_MaybeGC(JSContext *cx);
        3405                 :
        3406                 : extern JS_PUBLIC_API(void)
        3407                 : JS_SetGCCallback(JSRuntime *rt, JSGCCallback cb);
        3408                 :
        3409                 : extern JS_PUBLIC_API(void)
        3410                 : JS_SetFinalizeCallback(JSRuntime *rt, JSFinalizeCallback cb);
        3411                 :
        3412                 : extern JS_PUBLIC_API(JSBool)
        3413                 : JS_IsGCMarkingTracer(JSTracer *trc);
        3414                 :
        3415                 : extern JS_PUBLIC_API(JSBool)
        3416                 : JS_IsAboutToBeFinalized(void *thing);
        3417                 :
        3418                 : typedef enum JSGCParamKey {
        3419                 :     /* Maximum nominal heap before last ditch GC. */
        3420                 :     JSGC_MAX_BYTES          = 0,
        3421                 :
        3422                 :     /* Number of JS_malloc bytes before last ditch GC. */
        3423                 :     JSGC_MAX_MALLOC_BYTES   = 1,
        3424                 :
        3425                 :     /* Amount of bytes allocated by the GC. */
        3426                 :     JSGC_BYTES = 3,
        3427                 :
        3428                 :     /* Number of times when GC was invoked. */
        3429                 :     JSGC_NUMBER = 4,
        3430                 :
        3431                 :     /* Max size of the code cache in bytes. */
        3432                 :     JSGC_MAX_CODE_CACHE_BYTES = 5,
        3433                 :
        3434                 :     /* Select GC mode. */
        3435                 :     JSGC_MODE = 6,
        3436                 :
        3437                 :     /* Number of cached empty GC chunks. */
        3438                 :     JSGC_UNUSED_CHUNKS = 7,
        3439                 :
        3440                 :     /* Total number of allocated GC chunks. */
        3441                 :     JSGC_TOTAL_CHUNKS = 8,
        3442                 :
        3443                 :     /* Max milliseconds to spend in an incremental GC slice. */
        3444                 :     JSGC_SLICE_TIME_BUDGET = 9,
        3445                 :
        3446                 :     /* Maximum size the GC mark stack can grow to. */
        3447                 :     JSGC_MARK_STACK_LIMIT = 10
        3448                 : } JSGCParamKey;
        3449                 :
        3450                 : typedef enum JSGCMode {
        3451                 :     /* Perform only global GCs. */
        3452                 :     JSGC_MODE_GLOBAL = 0,
        3453                 :
        3454                 :     /* Perform per-compartment GCs until too much garbage has accumulated. */
        3455                 :     JSGC_MODE_COMPARTMENT = 1,
        3456                 :
        3457                 :     /*
        3458                 :      * Collect in short time slices rather than all at once. Implies
        3459                 :      * JSGC_MODE_COMPARTMENT.
        3460                 :      */
        3461                 :     JSGC_MODE_INCREMENTAL = 2
        3462                 : } JSGCMode;
        3463                 :
        3464                 : extern JS_PUBLIC_API(void)
        3465                 : JS_SetGCParameter(JSRuntime *rt, JSGCParamKey key, uint32_t value);
        3466                 :
        3467                 : extern JS_PUBLIC_API(uint32_t)
        3468                 : JS_GetGCParameter(JSRuntime *rt, JSGCParamKey key);
        3469                 :
        3470                 : extern JS_PUBLIC_API(void)
        3471                 : JS_SetGCParameterForThread(JSContext *cx, JSGCParamKey key, uint32_t value);
        3472                 :
        3473                 : extern JS_PUBLIC_API(uint32_t)
        3474                 : JS_GetGCParameterForThread(JSContext *cx, JSGCParamKey key);
        3475                 :
        3476                 : /*
        3477                 :  * Flush the code cache for the current thread. The operation might be
        3478                 :  * delayed if the cache cannot be flushed currently because native
        3479                 :  * code is currently executing.
        3480                 :  */
        3481                 :
        3482                 : extern JS_PUBLIC_API(void)
        3483                 : JS_FlushCaches(JSContext *cx);
        3484                 :
        3485                 : /*
        3486                 :  * Create a new JSString whose chars member refers to external memory, i.e.,
        3487                 :  * memory requiring application-specific finalization.
        3488                 :  */
        3489                 : extern JS_PUBLIC_API(JSString *)
        3490                 : JS_NewExternalString(JSContext *cx, const jschar *chars, size_t length,
        3491                 :                      const JSStringFinalizer *fin);
        3492                 :
        3493                 : /*
        3494                 :  * Return whether 'str' was created with JS_NewExternalString or
        3495                 :  * JS_NewExternalStringWithClosure.
        3496                 :  */
        3497                 : extern JS_PUBLIC_API(JSBool)
        3498                 : JS_IsExternalString(JSString *str);
        3499                 :
        3500                 : /*
        3501                 :  * Return the 'closure' arg passed to JS_NewExternalStringWithClosure or NULL
        3502                 :  * if the external string was created via JS_NewExternalString.
        3503                 :  */
        3504                 : extern JS_PUBLIC_API(const JSStringFinalizer *)
        3505                 : JS_GetExternalStringFinalizer(JSString *str);
        3506                 :
        3507                 : /*
        3508                 :  * Set the size of the native stack that should not be exceed. To disable
        3509                 :  * stack size checking pass 0.
        3510                 :  */
        3511                 : extern JS_PUBLIC_API(void)
        3512                 : JS_SetNativeStackQuota(JSRuntime *cx, size_t stackSize);
        3513                 :
        3514                 : /************************************************************************/
        3515                 :
        3516                 : /*
        3517                 :  * Classes, objects, and properties.
        3518                 :  */
        3519                 : typedef void (*JSClassInternal)();
        3520                 :
        3521                 : struct JSClass {
        3522                 :     const char          *name;
        3523                 :     uint32_t            flags;
        3524                 :
        3525                 :     /* Mandatory non-null function pointer members. */
        3526                 :     JSPropertyOp        addProperty;
        3527                 :     JSPropertyOp        delProperty;
        3528                 :     JSPropertyOp        getProperty;
        3529                 :     JSStrictPropertyOp  setProperty;
        3530                 :     JSEnumerateOp       enumerate;
        3531                 :     JSResolveOp         resolve;
        3532                 :     JSConvertOp         convert;
        3533                 :     JSFinalizeOp        finalize;
        3534                 :
        3535                 :     /* Optionally non-null members start here. */
        3536                 :     JSCheckAccessOp     checkAccess;
        3537                 :     JSNative            call;
        3538                 :     JSNative            construct;
        3539                 :     JSHasInstanceOp     hasInstance;
        3540                 :     JSTraceOp           trace;
        3541                 :
        3542                 :     void                *reserved[40];
        3543                 : };
        3544                 :
        3545                 : #define JSCLASS_HAS_PRIVATE             (1<<0)  /* objects have private slot */
        3546                 : #define JSCLASS_NEW_ENUMERATE           (1<<1)  /* has JSNewEnumerateOp hook */
        3547                 : #define JSCLASS_NEW_RESOLVE             (1<<2)  /* has JSNewResolveOp hook */
        3548                 : #define JSCLASS_PRIVATE_IS_NSISUPPORTS  (1<<3)  /* private is (nsISupports *) */
        3549                 : #define JSCLASS_NEW_RESOLVE_GETS_START  (1<<4)  /* JSNewResolveOp gets starting
        3550                 :                                                    object in prototype chain
        3551                 :                                                    passed in via *objp in/out
        3552                 :                                                    parameter */
        3553                 : #define JSCLASS_IMPLEMENTS_BARRIERS     (1<<5)  /* Correctly implements GC read
        3554                 :                                                    and write barriers */
        3555                 : #define JSCLASS_DOCUMENT_OBSERVER       (1<<6)  /* DOM document observer */
        3556                 : #define JSCLASS_USERBIT1                (1<<7)  /* Reserved for embeddings. */
        3557                 :
        3558                 : /*
        3559                 :  * To reserve slots fetched and stored via JS_Get/SetReservedSlot, bitwise-or
        3560                 :  * JSCLASS_HAS_RESERVED_SLOTS(n) into the initializer for JSClass.flags, where
        3561                 :  * n is a constant in [1, 255].  Reserved slots are indexed from 0 to n-1.
        3562                 :  */
        3563                 : #define JSCLASS_RESERVED_SLOTS_SHIFT    8       /* room for 8 flags below */
        3564                 : #define JSCLASS_RESERVED_SLOTS_WIDTH    8       /* and 16 above this field */
        3565                 : #define JSCLASS_RESERVED_SLOTS_MASK     JS_BITMASK(JSCLASS_RESERVED_SLOTS_WIDTH)
        3566                 : #define JSCLASS_HAS_RESERVED_SLOTS(n)   (((n) & JSCLASS_RESERVED_SLOTS_MASK)  \
        3567                 :                                          << JSCLASS_RESERVED_SLOTS_SHIFT)
        3568                 : #define JSCLASS_RESERVED_SLOTS(clasp)   (((clasp)->flags                      \
        3569                 :                                           >> JSCLASS_RESERVED_SLOTS_SHIFT)    \
        3570                 :                                          & JSCLASS_RESERVED_SLOTS_MASK)
        3571                 :
        3572                 : #define JSCLASS_HIGH_FLAGS_SHIFT        (JSCLASS_RESERVED_SLOTS_SHIFT +       \
        3573                 :                                          JSCLASS_RESERVED_SLOTS_WIDTH)
        3574                 :
        3575                 : /*
        3576                 :  * Call the iteratorObject hook only to iterate over contents (for-of), not to
        3577                 :  * enumerate properties (for-in, for-each, Object.keys, etc.)
        3578                 :  */
        3579                 : #define JSCLASS_FOR_OF_ITERATION        (1<<(JSCLASS_HIGH_FLAGS_SHIFT+0))
        3580                 :
        3581                 : #define JSCLASS_IS_ANONYMOUS            (1<<(JSCLASS_HIGH_FLAGS_SHIFT+1))
        3582                 : #define JSCLASS_IS_GLOBAL               (1<<(JSCLASS_HIGH_FLAGS_SHIFT+2))
        3583                 : #define JSCLASS_INTERNAL_FLAG2          (1<<(JSCLASS_HIGH_FLAGS_SHIFT+3))
        3584                 : #define JSCLASS_INTERNAL_FLAG3          (1<<(JSCLASS_HIGH_FLAGS_SHIFT+4))
        3585                 :
        3586                 : /* Indicate whether the proto or ctor should be frozen. */
        3587                 : #define JSCLASS_FREEZE_PROTO            (1<<(JSCLASS_HIGH_FLAGS_SHIFT+5))
        3588                 : #define JSCLASS_FREEZE_CTOR             (1<<(JSCLASS_HIGH_FLAGS_SHIFT+6))
        3589                 :
        3590                 : #define JSCLASS_XPCONNECT_GLOBAL        (1<<(JSCLASS_HIGH_FLAGS_SHIFT+7))
        3591                 :
        3592                 : /* Reserved for embeddings. */
        3593                 : #define JSCLASS_USERBIT2                (1<<(JSCLASS_HIGH_FLAGS_SHIFT+8))
        3594                 : #define JSCLASS_USERBIT3                (1<<(JSCLASS_HIGH_FLAGS_SHIFT+9))
        3595                 :
        3596                 : /*
        3597                 :  * Bits 26 through 31 are reserved for the CACHED_PROTO_KEY mechanism, see
        3598                 :  * below.
        3599                 :  */
        3600                 :
        3601                 : /* Global flags. */
        3602                 : #define JSGLOBAL_FLAGS_CLEARED          0x1
        3603                 :
        3604                 : /*
        3605                 :  * ECMA-262 requires that most constructors used internally create objects
        3606                 :  * with "the original Foo.prototype value" as their [[Prototype]] (__proto__)
        3607                 :  * member initial value.  The "original ... value" verbiage is there because
        3608                 :  * in ECMA-262, global properties naming class objects are read/write and
        3609                 :  * deleteable, for the most part.
        3610                 :  *
        3611                 :  * Implementing this efficiently requires that global objects have classes
        3612                 :  * with the following flags. Failure to use JSCLASS_GLOBAL_FLAGS was
        3613                 :  * prevously allowed, but is now an ES5 violation and thus unsupported.
        3614                 :  */
        3615                 : #define JSCLASS_GLOBAL_SLOT_COUNT      (JSProto_LIMIT * 3 + 8)
        3616                 : #define JSCLASS_GLOBAL_FLAGS_WITH_SLOTS(n)                                    \
        3617                 :     (JSCLASS_IS_GLOBAL | JSCLASS_HAS_RESERVED_SLOTS(JSCLASS_GLOBAL_SLOT_COUNT + (n)))
        3618                 : #define JSCLASS_GLOBAL_FLAGS                                                  \
        3619                 :     JSCLASS_GLOBAL_FLAGS_WITH_SLOTS(0)
        3620                 : #define JSCLASS_HAS_GLOBAL_FLAG_AND_SLOTS(clasp)                              \
        3621                 :   (((clasp)->flags & JSCLASS_IS_GLOBAL)                                       \
        3622                 :    && JSCLASS_RESERVED_SLOTS(clasp) >= JSCLASS_GLOBAL_SLOT_COUNT)
        3623                 :
        3624                 : /* Fast access to the original value of each standard class's prototype. */
        3625                 : #define JSCLASS_CACHED_PROTO_SHIFT      (JSCLASS_HIGH_FLAGS_SHIFT + 10)
        3626                 : #define JSCLASS_CACHED_PROTO_WIDTH      6
        3627                 : #define JSCLASS_CACHED_PROTO_MASK       JS_BITMASK(JSCLASS_CACHED_PROTO_WIDTH)
        3628                 : #define JSCLASS_HAS_CACHED_PROTO(key)   ((key) << JSCLASS_CACHED_PROTO_SHIFT)
        3629                 : #define JSCLASS_CACHED_PROTO_KEY(clasp) ((JSProtoKey)                         \
        3630                 :                                          (((clasp)->flags                     \
        3631                 :                                            >> JSCLASS_CACHED_PROTO_SHIFT)     \
        3632                 :                                           & JSCLASS_CACHED_PROTO_MASK))
        3633                 :
        3634                 : /* Initializer for unused members of statically initialized JSClass structs. */
        3635                 : #define JSCLASS_NO_INTERNAL_MEMBERS     {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0}
        3636                 : #define JSCLASS_NO_OPTIONAL_MEMBERS     0,0,0,0,0,JSCLASS_NO_INTERNAL_MEMBERS
        3637                 :
        3638                 : extern JS_PUBLIC_API(int)
        3639                 : JS_IdArrayLength(JSContext *cx, JSIdArray *ida);
        3640                 :
        3641                 : extern JS_PUBLIC_API(jsid)
        3642                 : JS_IdArrayGet(JSContext *cx, JSIdArray *ida, int index);
        3643                 :
        3644                 : extern JS_PUBLIC_API(void)
        3645                 : JS_DestroyIdArray(JSContext *cx, JSIdArray *ida);
        3646                 :
        3647                 : #ifdef __cplusplus
        3648                 :
        3649                 : namespace JS {
        3650                 :
        3651                 : class AutoIdArray : private AutoGCRooter {
        3652                 :   public:
        3653               0 :     AutoIdArray(JSContext *cx, JSIdArray *ida JS_GUARD_OBJECT_NOTIFIER_PARAM)
        3654               0 :       : AutoGCRooter(cx, IDARRAY), context(cx), idArray(ida)
        3655                 :     {
        3656               0 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        3657               0 :     }
        3658               0 :     ~AutoIdArray() {
        3659               0 :         if (idArray)
        3660               0 :             JS_DestroyIdArray(context, idArray);
        3661               0 :     }
        3662               0 :     bool operator!() {
        3663               0 :         return !idArray;
        3664                 :     }
        3665               0 :     jsid operator[](size_t i) const {
        3666               0 :         JS_ASSERT(idArray);
        3667               0 :         JS_ASSERT(i < length());
        3668               0 :         return JS_IdArrayGet(context, idArray, i);
        3669                 :     }
        3670               0 :     size_t length() const {
        3671               0 :         return JS_IdArrayLength(context, idArray);
        3672                 :     }
        3673                 :
        3674                 :     friend void AutoGCRooter::trace(JSTracer *trc);
        3675                 :
        3676                 :     JSIdArray *steal() {
        3677                 :         JSIdArray *copy = idArray;
        3678                 :         idArray = NULL;
        3679                 :         return copy;
        3680                 :     }
        3681                 :
        3682                 :   protected:
        3683                 :     inline void trace(JSTracer *trc);
        3684                 :
        3685                 :   private:
        3686                 :     JSContext *context;
        3687                 :     JSIdArray *idArray;
        3688                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        3689                 :
        3690                 :     /* No copy or assignment semantics. */
        3691                 :     AutoIdArray(AutoIdArray &ida) MOZ_DELETE;
        3692                 :     void operator=(AutoIdArray &ida) MOZ_DELETE;
        3693                 : };
        3694                 :
        3695                 : } /* namespace JS */
        3696                 :
        3697                 : #endif /* __cplusplus */
        3698                 :
        3699                 : extern JS_PUBLIC_API(JSBool)
        3700                 : JS_ValueToId(JSContext *cx, jsval v, jsid *idp);
        3701                 :
        3702                 : extern JS_PUBLIC_API(JSBool)
        3703                 : JS_IdToValue(JSContext *cx, jsid id, jsval *vp);
        3704                 :
        3705                 : /*
        3706                 :  * JSNewResolveOp flag bits.
        3707                 :  */
        3708                 : #define JSRESOLVE_QUALIFIED     0x01    /* resolve a qualified property id */
        3709                 : #define JSRESOLVE_ASSIGNING     0x02    /* resolve on the left of assignment */
        3710                 : #define JSRESOLVE_DETECTING     0x04    /* 'if (o.p)...' or '(o.p) ?...:...' */
        3711                 : #define JSRESOLVE_DECLARING     0x08    /* var, const, or function prolog op */
        3712                 : #define JSRESOLVE_CLASSNAME     0x10    /* class name used when constructing */
        3713                 : #define JSRESOLVE_WITH          0x20    /* resolve inside a with statement */
        3714                 :
        3715                 : /*
        3716                 :  * Invoke the [[DefaultValue]] hook (see ES5 8.6.2) with the provided hint on
        3717                 :  * the specified object, computing a primitive default value for the object.
        3718                 :  * The hint must be JSTYPE_STRING, JSTYPE_NUMBER, or JSTYPE_VOID (no hint).  On
        3719                 :  * success the resulting value is stored in *vp.
        3720                 :  */
        3721                 : extern JS_PUBLIC_API(JSBool)
        3722                 : JS_DefaultValue(JSContext *cx, JSObject *obj, JSType hint, jsval *vp);
        3723                 :
        3724                 : extern JS_PUBLIC_API(JSBool)
        3725                 : JS_PropertyStub(JSContext *cx, JSObject *obj, jsid id, jsval *vp);
        3726                 :
        3727                 : extern JS_PUBLIC_API(JSBool)
        3728                 : JS_StrictPropertyStub(JSContext *cx, JSObject *obj, jsid id, JSBool strict, jsval *vp);
        3729                 :
        3730                 : extern JS_PUBLIC_API(JSBool)
        3731                 : JS_EnumerateStub(JSContext *cx, JSObject *obj);
        3732                 :
        3733                 : extern JS_PUBLIC_API(JSBool)
        3734                 : JS_ResolveStub(JSContext *cx, JSObject *obj, jsid id);
        3735                 :
        3736                 : extern JS_PUBLIC_API(JSBool)
        3737                 : JS_ConvertStub(JSContext *cx, JSObject *obj, JSType type, jsval *vp);
        3738                 :
        3739                 : struct JSConstDoubleSpec {
        3740                 :     double          dval;
        3741                 :     const char      *name;
        3742                 :     uint8_t         flags;
        3743                 :     uint8_t         spare[3];
        3744                 : };
        3745                 :
        3746                 : /*
        3747                 :  * To define an array element rather than a named property member, cast the
        3748                 :  * element's index to (const char *) and initialize name with it, and set the
        3749                 :  * JSPROP_INDEX bit in flags.
        3750                 :  */
        3751                 : struct JSPropertySpec {
        3752                 :     const char            *name;
        3753                 :     int8_t                tinyid;
        3754                 :     uint8_t               flags;
        3755                 :     JSPropertyOp          getter;
        3756                 :     JSStrictPropertyOp    setter;
        3757                 : };
        3758                 :
        3759                 : struct JSFunctionSpec {
        3760                 :     const char      *name;
        3761                 :     JSNative        call;
        3762                 :     uint16_t        nargs;
        3763                 :     uint16_t        flags;
        3764                 : };
        3765                 :
        3766                 : /*
        3767                 :  * Terminating sentinel initializer to put at the end of a JSFunctionSpec array
        3768                 :  * that's passed to JS_DefineFunctions or JS_InitClass.
        3769                 :  */
        3770                 : #define JS_FS_END JS_FS(NULL,NULL,0,0)
        3771                 :
        3772                 : /*
        3773                 :  * Initializer macros for a JSFunctionSpec array element. JS_FN (whose name
        3774                 :  * pays homage to the old JSNative/JSFastNative split) simply adds the flag
        3775                 :  * JSFUN_STUB_GSOPS.
        3776                 :  */
        3777                 : #define JS_FS(name,call,nargs,flags)                                          \
        3778                 :     {name, call, nargs, flags}
        3779                 : #define JS_FN(name,call,nargs,flags)                                          \
        3780                 :     {name, call, nargs, (flags) | JSFUN_STUB_GSOPS}
        3781                 :
        3782                 : extern JS_PUBLIC_API(JSObject *)
        3783                 : JS_InitClass(JSContext *cx, JSObject *obj, JSObject *parent_proto,
        3784                 :              JSClass *clasp, JSNative constructor, unsigned nargs,
        3785                 :              JSPropertySpec *ps, JSFunctionSpec *fs,
        3786                 :              JSPropertySpec *static_ps, JSFunctionSpec *static_fs);
        3787                 :
        3788                 : /*
        3789                 :  * Set up ctor.prototype = proto and proto.constructor = ctor with the
        3790                 :  * right property flags.
        3791                 :  */
        3792                 : extern JS_PUBLIC_API(JSBool)
        3793                 : JS_LinkConstructorAndPrototype(JSContext *cx, JSObject *ctor, JSObject *proto);
        3794                 :
        3795                 : extern JS_PUBLIC_API(JSClass *)
        3796                 : JS_GetClass(JSObject *obj);
        3797                 :
        3798                 : extern JS_PUBLIC_API(JSBool)
        3799                 : JS_InstanceOf(JSContext *cx, JSObject *obj, JSClass *clasp, jsval *argv);
        3800                 :
        3801                 : extern JS_PUBLIC_API(JSBool)
        3802                 : JS_HasInstance(JSContext *cx, JSObject *obj, jsval v, JSBool *bp);
        3803                 :
        3804                 : extern JS_PUBLIC_API(void *)
        3805                 : JS_GetPrivate(JSObject *obj);
        3806                 :
        3807                 : extern JS_PUBLIC_API(void)
        3808                 : JS_SetPrivate(JSObject *obj, void *data);
        3809                 :
        3810                 : extern JS_PUBLIC_API(void *)
        3811                 : JS_GetInstancePrivate(JSContext *cx, JSObject *obj, JSClass *clasp,
        3812                 :                       jsval *argv);
        3813                 :
        3814                 : extern JS_PUBLIC_API(JSObject *)
        3815                 : JS_GetPrototype(JSObject *obj);
        3816                 :
        3817                 : extern JS_PUBLIC_API(JSBool)
        3818                 : JS_SetPrototype(JSContext *cx, JSObject *obj, JSObject *proto);
        3819                 :
        3820                 : extern JS_PUBLIC_API(JSObject *)
        3821                 : JS_GetParent(JSObject *obj);
        3822                 :
        3823                 : extern JS_PUBLIC_API(JSBool)
        3824                 : JS_SetParent(JSContext *cx, JSObject *obj, JSObject *parent);
        3825                 :
        3826                 : extern JS_PUBLIC_API(JSObject *)
        3827                 : JS_GetConstructor(JSContext *cx, JSObject *proto);
        3828                 :
        3829                 : /*
        3830                 :  * Get a unique identifier for obj, good for the lifetime of obj (even if it
        3831                 :  * is moved by a copying GC).  Return false on failure (likely out of memory),
        3832                 :  * and true with *idp containing the unique id on success.
        3833                 :  */
        3834                 : extern JS_PUBLIC_API(JSBool)
        3835                 : JS_GetObjectId(JSContext *cx, JSObject *obj, jsid *idp);
        3836                 :
        3837                 : extern JS_PUBLIC_API(JSObject *)
        3838                 : JS_NewGlobalObject(JSContext *cx, JSClass *clasp);
        3839                 :
        3840                 : extern JS_PUBLIC_API(JSObject *)
        3841                 : JS_NewCompartmentAndGlobalObject(JSContext *cx, JSClass *clasp, JSPrincipals *principals);
        3842                 :
        3843                 : extern JS_PUBLIC_API(JSObject *)
        3844                 : JS_NewObject(JSContext *cx, JSClass *clasp, JSObject *proto, JSObject *parent);
        3845                 :
        3846                 : /* Queries the [[Extensible]] property of the object. */
        3847                 : extern JS_PUBLIC_API(JSBool)
        3848                 : JS_IsExtensible(JSObject *obj);
        3849                 :
        3850                 : extern JS_PUBLIC_API(JSBool)
        3851                 : JS_IsNative(JSObject *obj);
        3852                 :
        3853                 : extern JS_PUBLIC_API(JSRuntime *)
        3854                 : JS_GetObjectRuntime(JSObject *obj);
        3855                 :
        3856                 : /*
        3857                 :  * Unlike JS_NewObject, JS_NewObjectWithGivenProto does not compute a default
        3858                 :  * proto if proto's actual parameter value is null.
        3859                 :  */
        3860                 : extern JS_PUBLIC_API(JSObject *)
        3861                 : JS_NewObjectWithGivenProto(JSContext *cx, JSClass *clasp, JSObject *proto,
        3862                 :                            JSObject *parent);
        3863                 :
        3864                 : /*
        3865                 :  * Freeze obj, and all objects it refers to, recursively. This will not recurse
        3866                 :  * through non-extensible objects, on the assumption that those are already
        3867                 :  * deep-frozen.
        3868                 :  */
        3869                 : extern JS_PUBLIC_API(JSBool)
        3870                 : JS_DeepFreezeObject(JSContext *cx, JSObject *obj);
        3871                 :
        3872                 : /*
        3873                 :  * Freezes an object; see ES5's Object.freeze(obj) method.
        3874                 :  */
        3875                 : extern JS_PUBLIC_API(JSBool)
        3876                 : JS_FreezeObject(JSContext *cx, JSObject *obj);
        3877                 :
        3878                 : extern JS_PUBLIC_API(JSObject *)
        3879                 : JS_ConstructObject(JSContext *cx, JSClass *clasp, JSObject *parent);
        3880                 :
        3881                 : extern JS_PUBLIC_API(JSObject *)
        3882                 : JS_ConstructObjectWithArguments(JSContext *cx, JSClass *clasp, JSObject *parent,
        3883                 :                                 unsigned argc, jsval *argv);
        3884                 :
        3885                 : extern JS_PUBLIC_API(JSObject *)
        3886                 : JS_New(JSContext *cx, JSObject *ctor, unsigned argc, jsval *argv);
        3887                 :
        3888                 : extern JS_PUBLIC_API(JSObject *)
        3889                 : JS_DefineObject(JSContext *cx, JSObject *obj, const char *name, JSClass *clasp,
        3890                 :                 JSObject *proto, unsigned attrs);
        3891                 :
        3892                 : extern JS_PUBLIC_API(JSBool)
        3893                 : JS_DefineConstDoubles(JSContext *cx, JSObject *obj, JSConstDoubleSpec *cds);
        3894                 :
        3895                 : extern JS_PUBLIC_API(JSBool)
        3896                 : JS_DefineProperties(JSContext *cx, JSObject *obj, JSPropertySpec *ps);
        3897                 :
        3898                 : extern JS_PUBLIC_API(JSBool)
        3899                 : JS_DefineProperty(JSContext *cx, JSObject *obj, const char *name, jsval value,
        3900                 :                   JSPropertyOp getter, JSStrictPropertyOp setter, unsigned attrs);
        3901                 :
        3902                 : extern JS_PUBLIC_API(JSBool)
        3903                 : JS_DefinePropertyById(JSContext *cx, JSObject *obj, jsid id, jsval value,
        3904                 :                       JSPropertyOp getter, JSStrictPropertyOp setter, unsigned attrs);
        3905                 :
        3906                 : extern JS_PUBLIC_API(JSBool)
        3907                 : JS_DefineOwnProperty(JSContext *cx, JSObject *obj, jsid id, jsval descriptor, JSBool *bp);
        3908                 :
        3909                 : /*
        3910                 :  * Determine the attributes (JSPROP_* flags) of a property on a given object.
        3911                 :  *
        3912                 :  * If the object does not have a property by that name, *foundp will be
        3913                 :  * JS_FALSE and the value of *attrsp is undefined.
        3914                 :  */
        3915                 : extern JS_PUBLIC_API(JSBool)
        3916                 : JS_GetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name,
        3917                 :                          unsigned *attrsp, JSBool *foundp);
        3918                 :
        3919                 : /*
        3920                 :  * The same, but if the property is native, return its getter and setter via
        3921                 :  * *getterp and *setterp, respectively (and only if the out parameter pointer
        3922                 :  * is not null).
        3923                 :  */
        3924                 : extern JS_PUBLIC_API(JSBool)
        3925                 : JS_GetPropertyAttrsGetterAndSetter(JSContext *cx, JSObject *obj,
        3926                 :                                    const char *name,
        3927                 :                                    unsigned *attrsp, JSBool *foundp,
        3928                 :                                    JSPropertyOp *getterp,
        3929                 :                                    JSStrictPropertyOp *setterp);
        3930                 :
        3931                 : extern JS_PUBLIC_API(JSBool)
        3932                 : JS_GetPropertyAttrsGetterAndSetterById(JSContext *cx, JSObject *obj,
        3933                 :                                        jsid id,
        3934                 :                                        unsigned *attrsp, JSBool *foundp,
        3935                 :                                        JSPropertyOp *getterp,
        3936                 :                                        JSStrictPropertyOp *setterp);
        3937                 :
        3938                 : /*
        3939                 :  * Set the attributes of a property on a given object.
        3940                 :  *
        3941                 :  * If the object does not have a property by that name, *foundp will be
        3942                 :  * JS_FALSE and nothing will be altered.
        3943                 :  */
        3944                 : extern JS_PUBLIC_API(JSBool)
        3945                 : JS_SetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name,
        3946                 :                          unsigned attrs, JSBool *foundp);
        3947                 :
        3948                 : extern JS_PUBLIC_API(JSBool)
        3949                 : JS_DefinePropertyWithTinyId(JSContext *cx, JSObject *obj, const char *name,
        3950                 :                             int8_t tinyid, jsval value,
        3951                 :                             JSPropertyOp getter, JSStrictPropertyOp setter,
        3952                 :                             unsigned attrs);
        3953                 :
        3954                 : extern JS_PUBLIC_API(JSBool)
        3955                 : JS_AlreadyHasOwnProperty(JSContext *cx, JSObject *obj, const char *name,
        3956                 :                          JSBool *foundp);
        3957                 :
        3958                 : extern JS_PUBLIC_API(JSBool)
        3959                 : JS_AlreadyHasOwnPropertyById(JSContext *cx, JSObject *obj, jsid id,
        3960                 :                              JSBool *foundp);
        3961                 :
        3962                 : extern JS_PUBLIC_API(JSBool)
        3963                 : JS_HasProperty(JSContext *cx, JSObject *obj, const char *name, JSBool *foundp);
        3964                 :
        3965                 : extern JS_PUBLIC_API(JSBool)
        3966                 : JS_HasPropertyById(JSContext *cx, JSObject *obj, jsid id, JSBool *foundp);
        3967                 :
        3968                 : extern JS_PUBLIC_API(JSBool)
        3969                 : JS_LookupProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
        3970                 :
        3971                 : extern JS_PUBLIC_API(JSBool)
        3972                 : JS_LookupPropertyById(JSContext *cx, JSObject *obj, jsid id, jsval *vp);
        3973                 :
        3974                 : extern JS_PUBLIC_API(JSBool)
        3975                 : JS_LookupPropertyWithFlags(JSContext *cx, JSObject *obj, const char *name,
        3976                 :                            unsigned flags, jsval *vp);
        3977                 :
        3978                 : extern JS_PUBLIC_API(JSBool)
        3979                 : JS_LookupPropertyWithFlagsById(JSContext *cx, JSObject *obj, jsid id,
        3980                 :                                unsigned flags, JSObject **objp, jsval *vp);
        3981                 :
        3982           14960 : struct JSPropertyDescriptor {
        3983                 :     JSObject           *obj;
        3984                 :     unsigned              attrs;
        3985                 :     JSPropertyOp       getter;
        3986                 :     JSStrictPropertyOp setter;
        3987                 :     jsval              value;
        3988                 :     unsigned              shortid;
        3989                 : };
        3990                 :
        3991                 : /*
        3992                 :  * Like JS_GetPropertyAttrsGetterAndSetterById but will return a property on
        3993                 :  * an object on the prototype chain (returned in objp). If data->obj is null,
        3994                 :  * then this property was not found on the prototype chain.
        3995                 :  */
        3996                 : extern JS_PUBLIC_API(JSBool)
        3997                 : JS_GetPropertyDescriptorById(JSContext *cx, JSObject *obj, jsid id, unsigned flags,
        3998                 :                              JSPropertyDescriptor *desc);
        3999                 :
        4000                 : extern JS_PUBLIC_API(JSBool)
        4001                 : JS_GetOwnPropertyDescriptor(JSContext *cx, JSObject *obj, jsid id, jsval *vp);
        4002                 :
        4003                 : extern JS_PUBLIC_API(JSBool)
        4004                 : JS_GetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
        4005                 :
        4006                 : extern JS_PUBLIC_API(JSBool)
        4007                 : JS_GetPropertyDefault(JSContext *cx, JSObject *obj, const char *name, jsval def, jsval *vp);
        4008                 :
        4009                 : extern JS_PUBLIC_API(JSBool)
        4010                 : JS_GetPropertyById(JSContext *cx, JSObject *obj, jsid id, jsval *vp);
        4011                 :
        4012                 : extern JS_PUBLIC_API(JSBool)
        4013                 : JS_GetPropertyByIdDefault(JSContext *cx, JSObject *obj, jsid id, jsval def, jsval *vp);
        4014                 :
        4015                 : extern JS_PUBLIC_API(JSBool)
        4016                 : JS_ForwardGetPropertyTo(JSContext *cx, JSObject *obj, jsid id, JSObject *onBehalfOf, jsval *vp);
        4017                 :
        4018                 : extern JS_PUBLIC_API(JSBool)
        4019                 : JS_GetMethodById(JSContext *cx, JSObject *obj, jsid id, JSObject **objp,
        4020                 :                  jsval *vp);
        4021                 :
        4022                 : extern JS_PUBLIC_API(JSBool)
        4023                 : JS_GetMethod(JSContext *cx, JSObject *obj, const char *name, JSObject **objp,
        4024                 :              jsval *vp);
        4025                 :
        4026                 : extern JS_PUBLIC_API(JSBool)
        4027                 : JS_SetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
        4028                 :
        4029                 : extern JS_PUBLIC_API(JSBool)
        4030                 : JS_SetPropertyById(JSContext *cx, JSObject *obj, jsid id, jsval *vp);
        4031                 :
        4032                 : extern JS_PUBLIC_API(JSBool)
        4033                 : JS_DeleteProperty(JSContext *cx, JSObject *obj, const char *name);
        4034                 :
        4035                 : extern JS_PUBLIC_API(JSBool)
        4036                 : JS_DeleteProperty2(JSContext *cx, JSObject *obj, const char *name,
        4037                 :                    jsval *rval);
        4038                 :
        4039                 : extern JS_PUBLIC_API(JSBool)
        4040                 : JS_DeletePropertyById(JSContext *cx, JSObject *obj, jsid id);
        4041                 :
        4042                 : extern JS_PUBLIC_API(JSBool)
        4043                 : JS_DeletePropertyById2(JSContext *cx, JSObject *obj, jsid id, jsval *rval);
        4044                 :
        4045                 : extern JS_PUBLIC_API(JSBool)
        4046                 : JS_DefineUCProperty(JSContext *cx, JSObject *obj,
        4047                 :                     const jschar *name, size_t namelen, jsval value,
        4048                 :                     JSPropertyOp getter, JSStrictPropertyOp setter,
        4049                 :                     unsigned attrs);
        4050                 :
        4051                 : /*
        4052                 :  * Determine the attributes (JSPROP_* flags) of a property on a given object.
        4053                 :  *
        4054                 :  * If the object does not have a property by that name, *foundp will be
        4055                 :  * JS_FALSE and the value of *attrsp is undefined.
        4056                 :  */
        4057                 : extern JS_PUBLIC_API(JSBool)
        4058                 : JS_GetUCPropertyAttributes(JSContext *cx, JSObject *obj,
        4059                 :                            const jschar *name, size_t namelen,
        4060                 :                            unsigned *attrsp, JSBool *foundp);
        4061                 :
        4062                 : /*
        4063                 :  * The same, but if the property is native, return its getter and setter via
        4064                 :  * *getterp and *setterp, respectively (and only if the out parameter pointer
        4065                 :  * is not null).
        4066                 :  */
        4067                 : extern JS_PUBLIC_API(JSBool)
        4068                 : JS_GetUCPropertyAttrsGetterAndSetter(JSContext *cx, JSObject *obj,
        4069                 :                                      const jschar *name, size_t namelen,
        4070                 :                                      unsigned *attrsp, JSBool *foundp,
        4071                 :                                      JSPropertyOp *getterp,
        4072                 :                                      JSStrictPropertyOp *setterp);
        4073                 :
        4074                 : /*
        4075                 :  * Set the attributes of a property on a given object.
        4076                 :  *
        4077                 :  * If the object does not have a property by that name, *foundp will be
        4078                 :  * JS_FALSE and nothing will be altered.
        4079                 :  */
        4080                 : extern JS_PUBLIC_API(JSBool)
        4081                 : JS_SetUCPropertyAttributes(JSContext *cx, JSObject *obj,
        4082                 :                            const jschar *name, size_t namelen,
        4083                 :                            unsigned attrs, JSBool *foundp);
        4084                 :
        4085                 :
        4086                 : extern JS_PUBLIC_API(JSBool)
        4087                 : JS_DefineUCPropertyWithTinyId(JSContext *cx, JSObject *obj,
        4088                 :                               const jschar *name, size_t namelen,
        4089                 :                               int8_t tinyid, jsval value,
        4090                 :                               JSPropertyOp getter, JSStrictPropertyOp setter,
        4091                 :                               unsigned attrs);
        4092                 :
        4093                 : extern JS_PUBLIC_API(JSBool)
        4094                 : JS_AlreadyHasOwnUCProperty(JSContext *cx, JSObject *obj, const jschar *name,
        4095                 :                            size_t namelen, JSBool *foundp);
        4096                 :
        4097                 : extern JS_PUBLIC_API(JSBool)
        4098                 : JS_HasUCProperty(JSContext *cx, JSObject *obj,
        4099                 :                  const jschar *name, size_t namelen,
        4100                 :                  JSBool *vp);
        4101                 :
        4102                 : extern JS_PUBLIC_API(JSBool)
        4103                 : JS_LookupUCProperty(JSContext *cx, JSObject *obj,
        4104                 :                     const jschar *name, size_t namelen,
        4105                 :                     jsval *vp);
        4106                 :
        4107                 : extern JS_PUBLIC_API(JSBool)
        4108                 : JS_GetUCProperty(JSContext *cx, JSObject *obj,
        4109                 :                  const jschar *name, size_t namelen,
        4110                 :                  jsval *vp);
        4111                 :
        4112                 : extern JS_PUBLIC_API(JSBool)
        4113                 : JS_SetUCProperty(JSContext *cx, JSObject *obj,
        4114                 :                  const jschar *name, size_t namelen,
        4115                 :                  jsval *vp);
        4116                 :
        4117                 : extern JS_PUBLIC_API(JSBool)
        4118                 : JS_DeleteUCProperty2(JSContext *cx, JSObject *obj,
        4119                 :                      const jschar *name, size_t namelen,
        4120                 :                      jsval *rval);
        4121                 :
        4122                 : extern JS_PUBLIC_API(JSObject *)
        4123                 : JS_NewArrayObject(JSContext *cx, int length, jsval *vector);
        4124                 :
        4125                 : extern JS_PUBLIC_API(JSBool)
        4126                 : JS_IsArrayObject(JSContext *cx, JSObject *obj);
        4127                 :
        4128                 : extern JS_PUBLIC_API(JSBool)
        4129                 : JS_GetArrayLength(JSContext *cx, JSObject *obj, uint32_t *lengthp);
        4130                 :
        4131                 : extern JS_PUBLIC_API(JSBool)
        4132                 : JS_SetArrayLength(JSContext *cx, JSObject *obj, uint32_t length);
        4133                 :
        4134                 : extern JS_PUBLIC_API(JSBool)
        4135                 : JS_DefineElement(JSContext *cx, JSObject *obj, uint32_t index, jsval value,
        4136                 :                  JSPropertyOp getter, JSStrictPropertyOp setter, unsigned attrs);
        4137                 :
        4138                 : extern JS_PUBLIC_API(JSBool)
        4139                 : JS_AlreadyHasOwnElement(JSContext *cx, JSObject *obj, uint32_t index, JSBool *foundp);
        4140                 :
        4141                 : extern JS_PUBLIC_API(JSBool)
        4142                 : JS_HasElement(JSContext *cx, JSObject *obj, uint32_t index, JSBool *foundp);
        4143                 :
        4144                 : extern JS_PUBLIC_API(JSBool)
        4145                 : JS_LookupElement(JSContext *cx, JSObject *obj, uint32_t index, jsval *vp);
        4146                 :
        4147                 : extern JS_PUBLIC_API(JSBool)
        4148                 : JS_GetElement(JSContext *cx, JSObject *obj, uint32_t index, jsval *vp);
        4149                 :
        4150                 : extern JS_PUBLIC_API(JSBool)
        4151                 : JS_ForwardGetElementTo(JSContext *cx, JSObject *obj, uint32_t index, JSObject *onBehalfOf,
        4152                 :                        jsval *vp);
        4153                 :
        4154                 : /*
        4155                 :  * Get the property with name given by |index|, if it has one.  If
        4156                 :  * not, |*present| will be set to false and the value of |vp| must not
        4157                 :  * be relied on.
        4158                 :  */
        4159                 : extern JS_PUBLIC_API(JSBool)
        4160                 : JS_GetElementIfPresent(JSContext *cx, JSObject *obj, uint32_t index, JSObject *onBehalfOf,
        4161                 :                        jsval *vp, JSBool* present);
        4162                 :
        4163                 : extern JS_PUBLIC_API(JSBool)
        4164                 : JS_SetElement(JSContext *cx, JSObject *obj, uint32_t index, jsval *vp);
        4165                 :
        4166                 : extern JS_PUBLIC_API(JSBool)
        4167                 : JS_DeleteElement(JSContext *cx, JSObject *obj, uint32_t index);
        4168                 :
        4169                 : extern JS_PUBLIC_API(JSBool)
        4170                 : JS_DeleteElement2(JSContext *cx, JSObject *obj, uint32_t index, jsval *rval);
        4171                 :
        4172                 : extern JS_PUBLIC_API(void)
        4173                 : JS_ClearScope(JSContext *cx, JSObject *obj);
        4174                 :
        4175                 : extern JS_PUBLIC_API(JSIdArray *)
        4176                 : JS_Enumerate(JSContext *cx, JSObject *obj);
        4177                 :
        4178                 : /*
        4179                 :  * Create an object to iterate over enumerable properties of obj, in arbitrary
        4180                 :  * property definition order.  NB: This differs from longstanding for..in loop
        4181                 :  * order, which uses order of property definition in obj.
        4182                 :  */
        4183                 : extern JS_PUBLIC_API(JSObject *)
        4184                 : JS_NewPropertyIterator(JSContext *cx, JSObject *obj);
        4185                 :
        4186                 : /*
        4187                 :  * Return true on success with *idp containing the id of the next enumerable
        4188                 :  * property to visit using iterobj, or JSID_IS_VOID if there is no such property
        4189                 :  * left to visit.  Return false on error.
        4190                 :  */
        4191                 : extern JS_PUBLIC_API(JSBool)
        4192                 : JS_NextProperty(JSContext *cx, JSObject *iterobj, jsid *idp);
        4193                 :
        4194                 : /*
        4195                 :  * Create an object to iterate over the elements of obj in for-of order. This
        4196                 :  * can be used to implement the iteratorObject hook for an array-like Class.
        4197                 :  */
        4198                 : extern JS_PUBLIC_API(JSObject *)
        4199                 : JS_NewElementIterator(JSContext *cx, JSObject *obj);
        4200                 :
        4201                 : /*
        4202                 :  * To make your array-like class iterable using the for-of loop, set the
        4203                 :  * JSCLASS_FOR_OF_ITERATION bit in the class's flags field and set its
        4204                 :  * .ext.iteratorObject hook to this function.
        4205                 :  */
        4206                 : extern JS_PUBLIC_API(JSObject *)
        4207                 : JS_ElementIteratorStub(JSContext *cx, JSObject *obj, JSBool keysonly);
        4208                 :
        4209                 : extern JS_PUBLIC_API(JSBool)
        4210                 : JS_CheckAccess(JSContext *cx, JSObject *obj, jsid id, JSAccessMode mode,
        4211                 :                jsval *vp, unsigned *attrsp);
        4212                 :
        4213                 : extern JS_PUBLIC_API(jsval)
        4214                 : JS_GetReservedSlot(JSObject *obj, uint32_t index);
        4215                 :
        4216                 : extern JS_PUBLIC_API(void)
        4217                 : JS_SetReservedSlot(JSObject *obj, uint32_t index, jsval v);
        4218                 :
        4219                 : /************************************************************************/
        4220                 :
        4221                 : /*
        4222                 :  * Security protocol.
        4223                 :  */
        4224               2 : struct JSPrincipals {
        4225                 :     /* Don't call "destroy"; use reference counting macros below. */
        4226                 :     int refcount;
        4227                 :
        4228                 : #ifdef DEBUG
        4229                 :     /* A helper to facilitate principals debugging. */
        4230                 :     uint32_t    debugToken;
        4231                 : #endif
        4232                 :
        4233                 : #ifdef __cplusplus
        4234                 :     void setDebugToken(uint32_t token) {
        4235                 : # ifdef DEBUG
        4236                 :         debugToken = token;
        4237                 : # endif
        4238                 :     }
        4239                 :
        4240                 :     /*
        4241                 :      * This is not defined by the JS engine but should be provided by the
        4242                 :      * embedding.
        4243                 :      */
        4244                 :     JS_PUBLIC_API(void) dump();
        4245                 : #endif
        4246                 : };
        4247                 :
        4248                 : extern JS_PUBLIC_API(void)
        4249                 : JS_HoldPrincipals(JSPrincipals *principals);
        4250                 :
        4251                 : extern JS_PUBLIC_API(void)
        4252                 : JS_DropPrincipals(JSRuntime *rt, JSPrincipals *principals);
        4253                 :
        4254                 : struct JSSecurityCallbacks {
        4255                 :     JSCheckAccessOp            checkObjectAccess;
        4256                 :     JSSubsumePrincipalsOp      subsumePrincipals;
        4257                 :     JSObjectPrincipalsFinder   findObjectPrincipals;
        4258                 :     JSCSPEvalChecker           contentSecurityPolicyAllows;
        4259                 :     JSPushContextPrincipalOp   pushContextPrincipal;
        4260                 :     JSPopContextPrincipalOp    popContextPrincipal;
        4261                 : };
        4262                 :
        4263                 : extern JS_PUBLIC_API(void)
        4264                 : JS_SetSecurityCallbacks(JSRuntime *rt, const JSSecurityCallbacks *callbacks);
        4265                 :
        4266                 : extern JS_PUBLIC_API(const JSSecurityCallbacks *)
        4267                 : JS_GetSecurityCallbacks(JSRuntime *rt);
        4268                 :
        4269                 : /*
        4270                 :  * Code running with "trusted" principals will be given a deeper stack
        4271                 :  * allocation than ordinary scripts. This allows trusted script to run after
        4272                 :  * untrusted script has exhausted the stack. This function sets the
        4273                 :  * runtime-wide trusted principal.
        4274                 :  *
        4275                 :  * This principals is not held (via JS_HoldPrincipals/JS_DropPrincipals) since
        4276                 :  * there is no available JSContext. Instead, the caller must ensure that the
        4277                 :  * given principals stays valid for as long as 'rt' may point to it. If the
        4278                 :  * principals would be destroyed before 'rt', JS_SetTrustedPrincipals must be
        4279                 :  * called again, passing NULL for 'prin'.
        4280                 :  */
        4281                 : extern JS_PUBLIC_API(void)
        4282                 : JS_SetTrustedPrincipals(JSRuntime *rt, JSPrincipals *prin);
        4283                 :
        4284                 : /*
        4285                 :  * Initialize the callback that is called to destroy JSPrincipals instance
        4286                 :  * when its reference counter drops to zero. The initialization can be done
        4287                 :  * only once per JS runtime.
        4288                 :  */
        4289                 : extern JS_PUBLIC_API(void)
        4290                 : JS_InitDestroyPrincipalsCallback(JSRuntime *rt, JSDestroyPrincipalsOp destroyPrincipals);
        4291                 :
        4292                 : /************************************************************************/
        4293                 :
        4294                 : /*
        4295                 :  * Functions and scripts.
        4296                 :  */
        4297                 : extern JS_PUBLIC_API(JSFunction *)
        4298                 : JS_NewFunction(JSContext *cx, JSNative call, unsigned nargs, unsigned flags,
        4299                 :                JSObject *parent, const char *name);
        4300                 :
        4301                 : /*
        4302                 :  * Create the function with the name given by the id. JSID_IS_STRING(id) must
        4303                 :  * be true.
        4304                 :  */
        4305                 : extern JS_PUBLIC_API(JSFunction *)
        4306                 : JS_NewFunctionById(JSContext *cx, JSNative call, unsigned nargs, unsigned flags,
        4307                 :                    JSObject *parent, jsid id);
        4308                 :
        4309                 : extern JS_PUBLIC_API(JSObject *)
        4310                 : JS_GetFunctionObject(JSFunction *fun);
        4311                 :
        4312                 : /*
        4313                 :  * Return the function's identifier as a JSString, or null if fun is unnamed.
        4314                 :  * The returned string lives as long as fun, so you don't need to root a saved
        4315                 :  * reference to it if fun is well-connected or rooted, and provided you bound
        4316                 :  * the use of the saved reference by fun's lifetime.
        4317                 :  */
        4318                 : extern JS_PUBLIC_API(JSString *)
        4319                 : JS_GetFunctionId(JSFunction *fun);
        4320                 :
        4321                 : /*
        4322                 :  * Return JSFUN_* flags for fun.
        4323                 :  */
        4324                 : extern JS_PUBLIC_API(unsigned)
        4325                 : JS_GetFunctionFlags(JSFunction *fun);
        4326                 :
        4327                 : /*
        4328                 :  * Return the arity (length) of fun.
        4329                 :  */
        4330                 : extern JS_PUBLIC_API(uint16_t)
        4331                 : JS_GetFunctionArity(JSFunction *fun);
        4332                 :
        4333                 : /*
        4334                 :  * Infallible predicate to test whether obj is a function object (faster than
        4335                 :  * comparing obj's class name to "Function", but equivalent unless someone has
        4336                 :  * overwritten the "Function" identifier with a different constructor and then
        4337                 :  * created instances using that constructor that might be passed in as obj).
        4338                 :  */
        4339                 : extern JS_PUBLIC_API(JSBool)
        4340                 : JS_ObjectIsFunction(JSContext *cx, JSObject *obj);
        4341                 :
        4342                 : extern JS_PUBLIC_API(JSBool)
        4343                 : JS_ObjectIsCallable(JSContext *cx, JSObject *obj);
        4344                 :
        4345                 : extern JS_PUBLIC_API(JSBool)
        4346                 : JS_IsNativeFunction(JSObject *funobj, JSNative call);
        4347                 :
        4348                 : /*
        4349                 :  * Bind the given callable to use the given object as "this".
        4350                 :  *
        4351                 :  * If |callable| is not callable, will throw and return NULL.
        4352                 :  */
        4353                 : extern JS_PUBLIC_API(JSObject*)
        4354                 : JS_BindCallable(JSContext *cx, JSObject *callable, JSObject *newThis);
        4355                 :
        4356                 : extern JS_PUBLIC_API(JSBool)
        4357                 : JS_DefineFunctions(JSContext *cx, JSObject *obj, JSFunctionSpec *fs);
        4358                 :
        4359                 : extern JS_PUBLIC_API(JSFunction *)
        4360                 : JS_DefineFunction(JSContext *cx, JSObject *obj, const char *name, JSNative call,
        4361                 :                   unsigned nargs, unsigned attrs);
        4362                 :
        4363                 : extern JS_PUBLIC_API(JSFunction *)
        4364                 : JS_DefineUCFunction(JSContext *cx, JSObject *obj,
        4365                 :                     const jschar *name, size_t namelen, JSNative call,
        4366                 :                     unsigned nargs, unsigned attrs);
        4367                 :
        4368                 : extern JS_PUBLIC_API(JSFunction *)
        4369                 : JS_DefineFunctionById(JSContext *cx, JSObject *obj, jsid id, JSNative call,
        4370                 :                       unsigned nargs, unsigned attrs);
        4371                 :
        4372                 : extern JS_PUBLIC_API(JSObject *)
        4373                 : JS_CloneFunctionObject(JSContext *cx, JSObject *funobj, JSObject *parent);
        4374                 :
        4375                 : /*
        4376                 :  * Given a buffer, return JS_FALSE if the buffer might become a valid
        4377                 :  * javascript statement with the addition of more lines.  Otherwise return
        4378                 :  * JS_TRUE.  The intent is to support interactive compilation - accumulate
        4379                 :  * lines in a buffer until JS_BufferIsCompilableUnit is true, then pass it to
        4380                 :  * the compiler.
        4381                 :  */
        4382                 : extern JS_PUBLIC_API(JSBool)
        4383                 : JS_BufferIsCompilableUnit(JSContext *cx, JSBool bytes_are_utf8,
        4384                 :                           JSObject *obj, const char *bytes, size_t length);
        4385                 :
        4386                 : extern JS_PUBLIC_API(JSScript *)
        4387                 : JS_CompileScript(JSContext *cx, JSObject *obj,
        4388                 :                  const char *bytes, size_t length,
        4389                 :                  const char *filename, unsigned lineno);
        4390                 :
        4391                 : extern JS_PUBLIC_API(JSScript *)
        4392                 : JS_CompileScriptForPrincipals(JSContext *cx, JSObject *obj,
        4393                 :                               JSPrincipals *principals,
        4394                 :                               const char *bytes, size_t length,
        4395                 :                               const char *filename, unsigned lineno);
        4396                 :
        4397                 : extern JS_PUBLIC_API(JSScript *)
        4398                 : JS_CompileScriptForPrincipalsVersion(JSContext *cx, JSObject *obj,
        4399                 :                                      JSPrincipals *principals,
        4400                 :                                      const char *bytes, size_t length,
        4401                 :                                      const char *filename, unsigned lineno,
        4402                 :                                      JSVersion version);
        4403                 :
        4404                 : extern JS_PUBLIC_API(JSScript *)
        4405                 : JS_CompileUCScript(JSContext *cx, JSObject *obj,
        4406                 :                    const jschar *chars, size_t length,
        4407                 :                    const char *filename, unsigned lineno);
        4408                 :
        4409                 : extern JS_PUBLIC_API(JSScript *)
        4410                 : JS_CompileUCScriptForPrincipals(JSContext *cx, JSObject *obj,
        4411                 :                                 JSPrincipals *principals,
        4412                 :                                 const jschar *chars, size_t length,
        4413                 :                                 const char *filename, unsigned lineno);
        4414                 :
        4415                 : extern JS_PUBLIC_API(JSScript *)
        4416                 : JS_CompileUCScriptForPrincipalsVersion(JSContext *cx, JSObject *obj,
        4417                 :                                        JSPrincipals *principals,
        4418                 :                                        const jschar *chars, size_t length,
        4419                 :                                        const char *filename, unsigned lineno,
        4420                 :                                        JSVersion version);
        4421                 : /*
        4422                 :  * If originPrincipals is null, then the value of principals is used as origin
        4423                 :  * principals for the compiled script.
        4424                 :  */
        4425                 : extern JS_PUBLIC_API(JSScript *)
        4426                 : JS_CompileUCScriptForPrincipalsVersionOrigin(JSContext *cx, JSObject *obj,
        4427                 :                                              JSPrincipals *principals,
        4428                 :                                              JSPrincipals *originPrincipals,
        4429                 :                                              const jschar *chars, size_t length,
        4430                 :                                              const char *filename, unsigned lineno,
        4431                 :                                              JSVersion version);
        4432                 :
        4433                 : extern JS_PUBLIC_API(JSScript *)
        4434                 : JS_CompileUTF8File(JSContext *cx, JSObject *obj, const char *filename);
        4435                 :
        4436                 : extern JS_PUBLIC_API(JSScript *)
        4437                 : JS_CompileUTF8FileHandle(JSContext *cx, JSObject *obj, const char *filename,
        4438                 :                          FILE *fh);
        4439                 :
        4440                 : extern JS_PUBLIC_API(JSScript *)
        4441                 : JS_CompileUTF8FileHandleForPrincipals(JSContext *cx, JSObject *obj,
        4442                 :                                       const char *filename, FILE *fh,
        4443                 :                                       JSPrincipals *principals);
        4444                 :
        4445                 : extern JS_PUBLIC_API(JSScript *)
        4446                 : JS_CompileUTF8FileHandleForPrincipalsVersion(JSContext *cx, JSObject *obj,
        4447                 :                                              const char *filename, FILE *fh,
        4448                 :                                              JSPrincipals *principals,
        4449                 :                                              JSVersion version);
        4450                 :
        4451                 : extern JS_PUBLIC_API(JSObject *)
        4452                 : JS_GetGlobalFromScript(JSScript *script);
        4453                 :
        4454                 : extern JS_PUBLIC_API(JSFunction *)
        4455                 : JS_CompileFunction(JSContext *cx, JSObject *obj, const char *name,
        4456                 :                    unsigned nargs, const char **argnames,
        4457                 :                    const char *bytes, size_t length,
        4458                 :                    const char *filename, unsigned lineno);
        4459                 :
        4460                 : extern JS_PUBLIC_API(JSFunction *)
        4461                 : JS_CompileFunctionForPrincipals(JSContext *cx, JSObject *obj,
        4462                 :                                 JSPrincipals *principals, const char *name,
        4463                 :                                 unsigned nargs, const char **argnames,
        4464                 :                                 const char *bytes, size_t length,
        4465                 :                                 const char *filename, unsigned lineno);
        4466                 :
        4467                 : extern JS_PUBLIC_API(JSFunction *)
        4468                 : JS_CompileUCFunction(JSContext *cx, JSObject *obj, const char *name,
        4469                 :                      unsigned nargs, const char **argnames,
        4470                 :                      const jschar *chars, size_t length,
        4471                 :                      const char *filename, unsigned lineno);
        4472                 :
        4473                 : extern JS_PUBLIC_API(JSFunction *)
        4474                 : JS_CompileUCFunctionForPrincipals(JSContext *cx, JSObject *obj,
        4475                 :                                   JSPrincipals *principals, const char *name,
        4476                 :                                   unsigned nargs, const char **argnames,
        4477                 :                                   const jschar *chars, size_t length,
        4478                 :                                   const char *filename, unsigned lineno);
        4479                 :
        4480                 : extern JS_PUBLIC_API(JSFunction *)
        4481                 : JS_CompileUCFunctionForPrincipalsVersion(JSContext *cx, JSObject *obj,
        4482                 :                                          JSPrincipals *principals, const char *name,
        4483                 :                                          unsigned nargs, const char **argnames,
        4484                 :                                          const jschar *chars, size_t length,
        4485                 :                                          const char *filename, unsigned lineno,
        4486                 :                                          JSVersion version);
        4487                 :
        4488                 : extern JS_PUBLIC_API(JSString *)
        4489                 : JS_DecompileScript(JSContext *cx, JSScript *script, const char *name, unsigned indent);
        4490                 :
        4491                 : /*
        4492                 :  * API extension: OR this into indent to avoid pretty-printing the decompiled
        4493                 :  * source resulting from JS_DecompileFunction{,Body}.
        4494                 :  */
        4495                 : #define JS_DONT_PRETTY_PRINT    ((unsigned)0x8000)
        4496                 :
        4497                 : extern JS_PUBLIC_API(JSString *)
        4498                 : JS_DecompileFunction(JSContext *cx, JSFunction *fun, unsigned indent);
        4499                 :
        4500                 : extern JS_PUBLIC_API(JSString *)
        4501                 : JS_DecompileFunctionBody(JSContext *cx, JSFunction *fun, unsigned indent);
        4502                 :
        4503                 : /*
        4504                 :  * NB: JS_ExecuteScript and the JS_Evaluate*Script* quadruplets use the obj
        4505                 :  * parameter as the initial scope chain header, the 'this' keyword value, and
        4506                 :  * the variables object (ECMA parlance for where 'var' and 'function' bind
        4507                 :  * names) of the execution context for script.
        4508                 :  *
        4509                 :  * Using obj as the variables object is problematic if obj's parent (which is
        4510                 :  * the scope chain link; see JS_SetParent and JS_NewObject) is not null: in
        4511                 :  * this case, variables created by 'var x = 0', e.g., go in obj, but variables
        4512                 :  * created by assignment to an unbound id, 'x = 0', go in the last object on
        4513                 :  * the scope chain linked by parent.
        4514                 :  *
        4515                 :  * ECMA calls that last scoping object the "global object", but note that many
        4516                 :  * embeddings have several such objects.  ECMA requires that "global code" be
        4517                 :  * executed with the variables object equal to this global object.  But these
        4518                 :  * JS API entry points provide freedom to execute code against a "sub-global",
        4519                 :  * i.e., a parented or scoped object, in which case the variables object will
        4520                 :  * differ from the last object on the scope chain, resulting in confusing and
        4521                 :  * non-ECMA explicit vs. implicit variable creation.
        4522                 :  *
        4523                 :  * Caveat embedders: unless you already depend on this buggy variables object
        4524                 :  * binding behavior, you should call JS_SetOptions(cx, JSOPTION_VAROBJFIX) or
        4525                 :  * JS_SetOptions(cx, JS_GetOptions(cx) | JSOPTION_VAROBJFIX) -- the latter if
        4526                 :  * someone may have set other options on cx already -- for each context in the
        4527                 :  * application, if you pass parented objects as the obj parameter, or may ever
        4528                 :  * pass such objects in the future.
        4529                 :  *
        4530                 :  * Why a runtime option?  The alternative is to add six or so new API entry
        4531                 :  * points with signatures matching the following six, and that doesn't seem
        4532                 :  * worth the code bloat cost.  Such new entry points would probably have less
        4533                 :  * obvious names, too, so would not tend to be used.  The JS_SetOption call,
        4534                 :  * OTOH, can be more easily hacked into existing code that does not depend on
        4535                 :  * the bug; such code can continue to use the familiar JS_EvaluateScript,
        4536                 :  * etc., entry points.
        4537                 :  */
        4538                 : extern JS_PUBLIC_API(JSBool)
        4539                 : JS_ExecuteScript(JSContext *cx, JSObject *obj, JSScript *script, jsval *rval);
        4540                 :
        4541                 : extern JS_PUBLIC_API(JSBool)
        4542                 : JS_ExecuteScriptVersion(JSContext *cx, JSObject *obj, JSScript *script, jsval *rval,
        4543                 :                         JSVersion version);
        4544                 :
        4545                 : /*
        4546                 :  * Execute either the function-defining prolog of a script, or the script's
        4547                 :  * main body, but not both.
        4548                 :  */
        4549                 : typedef enum JSExecPart { JSEXEC_PROLOG, JSEXEC_MAIN } JSExecPart;
        4550                 :
        4551                 : extern JS_PUBLIC_API(JSBool)
        4552                 : JS_EvaluateScript(JSContext *cx, JSObject *obj,
        4553                 :                   const char *bytes, unsigned length,
        4554                 :                   const char *filename, unsigned lineno,
        4555                 :                   jsval *rval);
        4556                 :
        4557                 : extern JS_PUBLIC_API(JSBool)
        4558                 : JS_EvaluateScriptForPrincipals(JSContext *cx, JSObject *obj,
        4559                 :                                JSPrincipals *principals,
        4560                 :                                const char *bytes, unsigned length,
        4561                 :                                const char *filename, unsigned lineno,
        4562                 :                                jsval *rval);
        4563                 :
        4564                 : extern JS_PUBLIC_API(JSBool)
        4565                 : JS_EvaluateScriptForPrincipalsVersion(JSContext *cx, JSObject *obj,
        4566                 :                                       JSPrincipals *principals,
        4567                 :                                       const char *bytes, unsigned length,
        4568                 :                                       const char *filename, unsigned lineno,
        4569                 :                                       jsval *rval, JSVersion version);
        4570                 :
        4571                 : extern JS_PUBLIC_API(JSBool)
        4572                 : JS_EvaluateUCScript(JSContext *cx, JSObject *obj,
        4573                 :                     const jschar *chars, unsigned length,
        4574                 :                     const char *filename, unsigned lineno,
        4575                 :                     jsval *rval);
        4576                 :
        4577                 : extern JS_PUBLIC_API(JSBool)
        4578                 : JS_EvaluateUCScriptForPrincipals(JSContext *cx, JSObject *obj,
        4579                 :                                  JSPrincipals *principals,
        4580                 :                                  const jschar *chars, unsigned length,
        4581                 :                                  const char *filename, unsigned lineno,
        4582                 :                                  jsval *rval);
        4583                 :
        4584                 : extern JS_PUBLIC_API(JSBool)
        4585                 : JS_EvaluateUCScriptForPrincipalsVersion(JSContext *cx, JSObject *obj,
        4586                 :                                         JSPrincipals *principals,
        4587                 :                                         const jschar *chars, unsigned length,
        4588                 :                                         const char *filename, unsigned lineno,
        4589                 :                                         jsval *rval, JSVersion version);
        4590                 :
        4591                 : /*
        4592                 :  * JSAPI clients may optionally specify the 'originPrincipals' of a script.
        4593                 :  * A script's originPrincipals may be retrieved through the debug API (via
        4594                 :  * JS_GetScriptOriginPrincipals) and the originPrincipals are transitively
        4595                 :  * assigned to any nested scripts (including scripts dynamically created via
        4596                 :  * eval and the Function constructor). If originPrincipals is null, then the
        4597                 :  * value of principals is used as origin principals for the script.
        4598                 :  */
        4599                 : extern JS_PUBLIC_API(JSBool)
        4600                 : JS_EvaluateUCScriptForPrincipalsVersionOrigin(JSContext *cx, JSObject *obj,
        4601                 :                                               JSPrincipals *principals,
        4602                 :                                               JSPrincipals *originPrincipals,
        4603                 :                                               const jschar *chars, unsigned length,
        4604                 :                                               const char *filename, unsigned lineno,
        4605                 :                                               jsval *rval, JSVersion version);
        4606                 :
        4607                 : extern JS_PUBLIC_API(JSBool)
        4608                 : JS_CallFunction(JSContext *cx, JSObject *obj, JSFunction *fun, unsigned argc,
        4609                 :                 jsval *argv, jsval *rval);
        4610                 :
        4611                 : extern JS_PUBLIC_API(JSBool)
        4612                 : JS_CallFunctionName(JSContext *cx, JSObject *obj, const char *name, unsigned argc,
        4613                 :                     jsval *argv, jsval *rval);
        4614                 :
        4615                 : extern JS_PUBLIC_API(JSBool)
        4616                 : JS_CallFunctionValue(JSContext *cx, JSObject *obj, jsval fval, unsigned argc,
        4617                 :                      jsval *argv, jsval *rval);
        4618                 :
        4619                 : #ifdef __cplusplus
        4620                 : JS_END_EXTERN_C
        4621                 :
        4622                 : namespace JS {
        4623                 :
        4624                 : static inline bool
        4625                 : Call(JSContext *cx, JSObject *thisObj, JSFunction *fun, unsigned argc, jsval *argv, jsval *rval) {
        4626                 :     return !!JS_CallFunction(cx, thisObj, fun, argc, argv, rval);
        4627                 : }
        4628                 :
        4629                 : static inline bool
        4630                 : Call(JSContext *cx, JSObject *thisObj, const char *name, unsigned argc, jsval *argv, jsval *rval) {
        4631                 :     return !!JS_CallFunctionName(cx, thisObj, name, argc, argv, rval);
        4632                 : }
        4633                 :
        4634                 : static inline bool
        4635                 : Call(JSContext *cx, JSObject *thisObj, jsval fun, unsigned argc, jsval *argv, jsval *rval) {
        4636                 :     return !!JS_CallFunctionValue(cx, thisObj, fun, argc, argv, rval);
        4637                 : }
        4638                 :
        4639                 : extern JS_PUBLIC_API(bool)
        4640                 : Call(JSContext *cx, jsval thisv, jsval fun, unsigned argc, jsval *argv, jsval *rval);
        4641                 :
        4642                 : static inline bool
        4643                 : Call(JSContext *cx, jsval thisv, JSObject *funObj, unsigned argc, jsval *argv, jsval *rval) {
        4644                 :     return Call(cx, thisv, OBJECT_TO_JSVAL(funObj), argc, argv, rval);
        4645                 : }
        4646                 :
        4647                 : } /* namespace JS */
        4648                 :
        4649                 : JS_BEGIN_EXTERN_C
        4650                 : #endif /* __cplusplus */
        4651                 :
        4652                 : /*
        4653                 :  * These functions allow setting an operation callback that will be called
        4654                 :  * from the JS thread some time after any thread triggered the callback using
        4655                 :  * JS_TriggerOperationCallback(rt).
        4656                 :  *
        4657                 :  * To schedule the GC and for other activities the engine internally triggers
        4658                 :  * operation callbacks. The embedding should thus not rely on callbacks being
        4659                 :  * triggered through the external API only.
        4660                 :  *
        4661                 :  * Important note: Additional callbacks can occur inside the callback handler
        4662                 :  * if it re-enters the JS engine. The embedding must ensure that the callback
        4663                 :  * is disconnected before attempting such re-entry.
        4664                 :  */
        4665                 : extern JS_PUBLIC_API(JSOperationCallback)
        4666                 : JS_SetOperationCallback(JSContext *cx, JSOperationCallback callback);
        4667                 :
        4668                 : extern JS_PUBLIC_API(JSOperationCallback)
        4669                 : JS_GetOperationCallback(JSContext *cx);
        4670                 :
        4671                 : extern JS_PUBLIC_API(void)
        4672                 : JS_TriggerOperationCallback(JSRuntime *rt);
        4673                 :
        4674                 : extern JS_PUBLIC_API(JSBool)
        4675                 : JS_IsRunning(JSContext *cx);
        4676                 :
        4677                 : /*
        4678                 :  * Saving and restoring frame chains.
        4679                 :  *
        4680                 :  * These two functions are used to set aside cx's call stack while that stack
        4681                 :  * is inactive. After a call to JS_SaveFrameChain, it looks as if there is no
        4682                 :  * code running on cx. Before calling JS_RestoreFrameChain, cx's call stack
        4683                 :  * must be balanced and all nested calls to JS_SaveFrameChain must have had
        4684                 :  * matching JS_RestoreFrameChain calls.
        4685                 :  *
        4686                 :  * JS_SaveFrameChain deals with cx not having any code running on it.
        4687                 :  */
        4688                 : extern JS_PUBLIC_API(JSBool)
        4689                 : JS_SaveFrameChain(JSContext *cx);
        4690                 :
        4691                 : extern JS_PUBLIC_API(void)
        4692                 : JS_RestoreFrameChain(JSContext *cx);
        4693                 :
        4694                 : #ifdef MOZ_TRACE_JSCALLS
        4695                 : /*
        4696                 :  * The callback is expected to be quick and noninvasive. It should not
        4697                 :  * trigger interrupts, turn on debugging, or produce uncaught JS
        4698                 :  * exceptions. The state of the stack and registers in the context
        4699                 :  * cannot be relied upon, since this callback may be invoked directly
        4700                 :  * from either JIT. The 'entering' field means we are entering a
        4701                 :  * function if it is positive, leaving a function if it is zero or
        4702                 :  * negative.
        4703                 :  */
        4704                 : extern JS_PUBLIC_API(void)
        4705                 : JS_SetFunctionCallback(JSContext *cx, JSFunctionCallback fcb);
        4706                 :
        4707                 : extern JS_PUBLIC_API(JSFunctionCallback)
        4708                 : JS_GetFunctionCallback(JSContext *cx);
        4709                 : #endif /* MOZ_TRACE_JSCALLS */
        4710                 :
        4711                 : /************************************************************************/
        4712                 :
        4713                 : /*
        4714                 :  * Strings.
        4715                 :  *
        4716                 :  * NB: JS_NewUCString takes ownership of bytes on success, avoiding a copy;
        4717                 :  * but on error (signified by null return), it leaves chars owned by the
        4718                 :  * caller. So the caller must free bytes in the error case, if it has no use
        4719                 :  * for them. In contrast, all the JS_New*StringCopy* functions do not take
        4720                 :  * ownership of the character memory passed to them -- they copy it.
        4721                 :  */
        4722                 : extern JS_PUBLIC_API(JSString *)
        4723                 : JS_NewStringCopyN(JSContext *cx, const char *s, size_t n);
        4724                 :
        4725                 : extern JS_PUBLIC_API(JSString *)
        4726                 : JS_NewStringCopyZ(JSContext *cx, const char *s);
        4727                 :
        4728                 : extern JS_PUBLIC_API(JSString *)
        4729                 : JS_InternJSString(JSContext *cx, JSString *str);
        4730                 :
        4731                 : extern JS_PUBLIC_API(JSString *)
        4732                 : JS_InternString(JSContext *cx, const char *s);
        4733                 :
        4734                 : extern JS_PUBLIC_API(JSString *)
        4735                 : JS_NewUCString(JSContext *cx, jschar *chars, size_t length);
        4736                 :
        4737                 : extern JS_PUBLIC_API(JSString *)
        4738                 : JS_NewUCStringCopyN(JSContext *cx, const jschar *s, size_t n);
        4739                 :
        4740                 : extern JS_PUBLIC_API(JSString *)
        4741                 : JS_NewUCStringCopyZ(JSContext *cx, const jschar *s);
        4742                 :
        4743                 : extern JS_PUBLIC_API(JSString *)
        4744                 : JS_InternUCStringN(JSContext *cx, const jschar *s, size_t length);
        4745                 :
        4746                 : extern JS_PUBLIC_API(JSString *)
        4747                 : JS_InternUCString(JSContext *cx, const jschar *s);
        4748                 :
        4749                 : extern JS_PUBLIC_API(JSBool)
        4750                 : JS_CompareStrings(JSContext *cx, JSString *str1, JSString *str2, int32_t *result);
        4751                 :
        4752                 : extern JS_PUBLIC_API(JSBool)
        4753                 : JS_StringEqualsAscii(JSContext *cx, JSString *str, const char *asciiBytes, JSBool *match);
        4754                 :
        4755                 : extern JS_PUBLIC_API(size_t)
        4756                 : JS_PutEscapedString(JSContext *cx, char *buffer, size_t size, JSString *str, char quote);
        4757                 :
        4758                 : extern JS_PUBLIC_API(JSBool)
        4759                 : JS_FileEscapedString(FILE *fp, JSString *str, char quote);
        4760                 :
        4761                 : /*
        4762                 :  * Extracting string characters and length.
        4763                 :  *
        4764                 :  * While getting the length of a string is infallible, getting the chars can
        4765                 :  * fail. As indicated by the lack of a JSContext parameter, there are two
        4766                 :  * special cases where getting the chars is infallible:
        4767                 :  *
        4768                 :  * The first case is interned strings, i.e., strings from JS_InternString or
        4769                 :  * JSID_TO_STRING(id), using JS_GetInternedStringChars*.
        4770                 :  *
        4771                 :  * The second case is "flat" strings that have been explicitly prepared in a
        4772                 :  * fallible context by JS_FlattenString. To catch errors, a separate opaque
        4773                 :  * JSFlatString type is returned by JS_FlattenString and expected by
        4774                 :  * JS_GetFlatStringChars. Note, though, that this is purely a syntactic
        4775                 :  * distinction: the input and output of JS_FlattenString are the same actual
        4776                 :  * GC-thing so only one needs to be rooted. If a JSString is known to be flat,
        4777                 :  * JS_ASSERT_STRING_IS_FLAT can be used to make a debug-checked cast. Example:
        4778                 :  *
        4779                 :  *   // in a fallible context
        4780                 :  *   JSFlatString *fstr = JS_FlattenString(cx, str);
        4781                 :  *   if (!fstr)
        4782                 :  *     return JS_FALSE;
        4783                 :  *   JS_ASSERT(fstr == JS_ASSERT_STRING_IS_FLAT(str));
        4784                 :  *
        4785                 :  *   // in an infallible context, for the same 'str'
        4786                 :  *   const jschar *chars = JS_GetFlatStringChars(fstr)
        4787                 :  *   JS_ASSERT(chars);
        4788                 :  *
        4789                 :  * The CharsZ APIs guarantee that the returned array has a null character at
        4790                 :  * chars[length]. This can require additional copying so clients should prefer
        4791                 :  * APIs without CharsZ if possible. The infallible functions also return
        4792                 :  * null-terminated arrays. (There is no additional cost or non-Z alternative
        4793                 :  * for the infallible functions, so 'Z' is left out of the identifier.)
        4794                 :  */
        4795                 :
        4796                 : extern JS_PUBLIC_API(size_t)
        4797                 : JS_GetStringLength(JSString *str);
        4798                 :
        4799                 : extern JS_PUBLIC_API(const jschar *)
        4800                 : JS_GetStringCharsAndLength(JSContext *cx, JSString *str, size_t *length);
        4801                 :
        4802                 : extern JS_PUBLIC_API(const jschar *)
        4803                 : JS_GetInternedStringChars(JSString *str);
        4804                 :
        4805                 : extern JS_PUBLIC_API(const jschar *)
        4806                 : JS_GetInternedStringCharsAndLength(JSString *str, size_t *length);
        4807                 :
        4808                 : extern JS_PUBLIC_API(const jschar *)
        4809                 : JS_GetStringCharsZ(JSContext *cx, JSString *str);
        4810                 :
        4811                 : extern JS_PUBLIC_API(const jschar *)
        4812                 : JS_GetStringCharsZAndLength(JSContext *cx, JSString *str, size_t *length);
        4813                 :
        4814                 : extern JS_PUBLIC_API(JSFlatString *)
        4815                 : JS_FlattenString(JSContext *cx, JSString *str);
        4816                 :
        4817                 : extern JS_PUBLIC_API(const jschar *)
        4818                 : JS_GetFlatStringChars(JSFlatString *str);
        4819                 :
        4820                 : static JS_ALWAYS_INLINE JSFlatString *
        4821        41665897 : JSID_TO_FLAT_STRING(jsid id)
        4822                 : {
        4823        41665897 :     JS_ASSERT(JSID_IS_STRING(id));
        4824        41665897 :     return (JSFlatString *)(JSID_BITS(id));
        4825                 : }
        4826                 :
        4827                 : static JS_ALWAYS_INLINE JSFlatString *
        4828               8 : JS_ASSERT_STRING_IS_FLAT(JSString *str)
        4829                 : {
        4830               8 :     JS_ASSERT(JS_GetFlatStringChars((JSFlatString *)str));
        4831               8 :     return (JSFlatString *)str;
        4832                 : }
        4833                 :
        4834                 : static JS_ALWAYS_INLINE JSString *
        4835                 : JS_FORGET_STRING_FLATNESS(JSFlatString *fstr)
        4836                 : {
        4837                 :     return (JSString *)fstr;
        4838                 : }
        4839                 :
        4840                 : /*
        4841                 :  * Additional APIs that avoid fallibility when given a flat string.
        4842                 :  */
        4843                 :
        4844                 : extern JS_PUBLIC_API(JSBool)
        4845                 : JS_FlatStringEqualsAscii(JSFlatString *str, const char *asciiBytes);
        4846                 :
        4847                 : extern JS_PUBLIC_API(size_t)
        4848                 : JS_PutEscapedFlatString(char *buffer, size_t size, JSFlatString *str, char quote);
        4849                 :
        4850                 : /*
        4851                 :  * This function is now obsolete and behaves the same as JS_NewUCString.  Use
        4852                 :  * JS_NewUCString instead.
        4853                 :  */
        4854                 : extern JS_PUBLIC_API(JSString *)
        4855                 : JS_NewGrowableString(JSContext *cx, jschar *chars, size_t length);
        4856                 :
        4857                 : /*
        4858                 :  * Mutable string support.  A string's characters are never mutable in this JS
        4859                 :  * implementation, but a dependent string is a substring of another dependent
        4860                 :  * or immutable string, and a rope is a lazily concatenated string that creates
        4861                 :  * its underlying buffer the first time it is accessed.  Even after a rope
        4862                 :  * creates its underlying buffer, it still considered mutable.  The direct data
        4863                 :  * members of the (opaque to API clients) JSString struct may be changed in a
        4864                 :  * single-threaded way for dependent strings and ropes.
        4865                 :  *
        4866                 :  * Therefore mutable strings (ropes and dependent strings) cannot be used by
        4867                 :  * more than one thread at a time.  You may call JS_MakeStringImmutable to
        4868                 :  * convert the string from a mutable string to an immutable (and therefore
        4869                 :  * thread-safe) string.  The engine takes care of converting ropes and dependent
        4870                 :  * strings to immutable for you if you store strings in multi-threaded objects
        4871                 :  * using JS_SetProperty or kindred API entry points.
        4872                 :  *
        4873                 :  * If you store a JSString pointer in a native data structure that is (safely)
        4874                 :  * accessible to multiple threads, you must call JS_MakeStringImmutable before
        4875                 :  * retiring the store.
        4876                 :  */
        4877                 :
        4878                 : /*
        4879                 :  * Create a dependent string, i.e., a string that owns no character storage,
        4880                 :  * but that refers to a slice of another string's chars.  Dependent strings
        4881                 :  * are mutable by definition, so the thread safety comments above apply.
        4882                 :  */
        4883                 : extern JS_PUBLIC_API(JSString *)
        4884                 : JS_NewDependentString(JSContext *cx, JSString *str, size_t start,
        4885                 :                       size_t length);
        4886                 :
        4887                 : /*
        4888                 :  * Concatenate two strings, possibly resulting in a rope.
        4889                 :  * See above for thread safety comments.
        4890                 :  */
        4891                 : extern JS_PUBLIC_API(JSString *)
        4892                 : JS_ConcatStrings(JSContext *cx, JSString *left, JSString *right);
        4893                 :
        4894                 : /*
        4895                 :  * Convert a dependent string into an independent one.  This function does not
        4896                 :  * change the string's mutability, so the thread safety comments above apply.
        4897                 :  */
        4898                 : extern JS_PUBLIC_API(const jschar *)
        4899                 : JS_UndependString(JSContext *cx, JSString *str);
        4900                 :
        4901                 : /*
        4902                 :  * Convert a mutable string (either rope or dependent) into an immutable,
        4903                 :  * thread-safe one.
        4904                 :  */
        4905                 : extern JS_PUBLIC_API(JSBool)
        4906                 : JS_MakeStringImmutable(JSContext *cx, JSString *str);
        4907                 :
        4908                 : /*
        4909                 :  * Return JS_TRUE if C (char []) strings passed via the API and internally
        4910                 :  * are UTF-8.
        4911                 :  */
        4912                 : JS_PUBLIC_API(JSBool)
        4913                 : JS_CStringsAreUTF8(void);
        4914                 :
        4915                 : /*
        4916                 :  * Update the value to be returned by JS_CStringsAreUTF8(). Once set, it
        4917                 :  * can never be changed. This API must be called before the first call to
        4918                 :  * JS_NewRuntime.
        4919                 :  */
        4920                 : JS_PUBLIC_API(void)
        4921                 : JS_SetCStringsAreUTF8(void);
        4922                 :
        4923                 : /*
        4924                 :  * Character encoding support.
        4925                 :  *
        4926                 :  * For both JS_EncodeCharacters and JS_DecodeBytes, set *dstlenp to the size
        4927                 :  * of the destination buffer before the call; on return, *dstlenp contains the
        4928                 :  * number of bytes (JS_EncodeCharacters) or jschars (JS_DecodeBytes) actually
        4929                 :  * stored.  To determine the necessary destination buffer size, make a sizing
        4930                 :  * call that passes NULL for dst.
        4931                 :  *
        4932                 :  * On errors, the functions report the error. In that case, *dstlenp contains
        4933                 :  * the number of characters or bytes transferred so far.  If cx is NULL, no
        4934                 :  * error is reported on failure, and the functions simply return JS_FALSE.
        4935                 :  *
        4936                 :  * NB: Neither function stores an additional zero byte or jschar after the
        4937                 :  * transcoded string.
        4938                 :  *
        4939                 :  * If JS_CStringsAreUTF8() is true then JS_EncodeCharacters encodes to
        4940                 :  * UTF-8, and JS_DecodeBytes decodes from UTF-8, which may create additional
        4941                 :  * errors if the character sequence is malformed.  If UTF-8 support is
        4942                 :  * disabled, the functions deflate and inflate, respectively.
        4943                 :  *
        4944                 :  * JS_DecodeUTF8() always behaves the same independently of JS_CStringsAreUTF8().
        4945                 :  */
        4946                 : JS_PUBLIC_API(JSBool)
        4947                 : JS_EncodeCharacters(JSContext *cx, const jschar *src, size_t srclen, char *dst,
        4948                 :                     size_t *dstlenp);
        4949                 :
        4950                 : JS_PUBLIC_API(JSBool)
        4951                 : JS_DecodeBytes(JSContext *cx, const char *src, size_t srclen, jschar *dst,
        4952                 :                size_t *dstlenp);
        4953                 :
        4954                 : JS_PUBLIC_API(JSBool)
        4955                 : JS_DecodeUTF8(JSContext *cx, const char *src, size_t srclen, jschar *dst,
        4956                 :               size_t *dstlenp);
        4957                 :
        4958                 : /*
        4959                 :  * A variation on JS_EncodeCharacters where a null terminated string is
        4960                 :  * returned that you are expected to call JS_free on when done.
        4961                 :  */
        4962                 : JS_PUBLIC_API(char *)
        4963                 : JS_EncodeString(JSContext *cx, JSString *str);
        4964                 :
        4965                 : /*
        4966                 :  * Get number of bytes in the string encoding (without accounting for a
        4967                 :  * terminating zero bytes. The function returns (size_t) -1 if the string
        4968                 :  * can not be encoded into bytes and reports an error using cx accordingly.
        4969                 :  */
        4970                 : JS_PUBLIC_API(size_t)
        4971                 : JS_GetStringEncodingLength(JSContext *cx, JSString *str);
        4972                 :
        4973                 : /*
        4974                 :  * Encode string into a buffer. The function does not stores an additional
        4975                 :  * zero byte. The function returns (size_t) -1 if the string can not be
        4976                 :  * encoded into bytes with no error reported. Otherwise it returns the number
        4977                 :  * of bytes that are necessary to encode the string. If that exceeds the
        4978                 :  * length parameter, the string will be cut and only length bytes will be
        4979                 :  * written into the buffer.
        4980                 :  *
        4981                 :  * If JS_CStringsAreUTF8() is true, the string does not fit into the buffer
        4982                 :  * and the the first length bytes ends in the middle of utf-8 encoding for
        4983                 :  * some character, then such partial utf-8 encoding is replaced by zero bytes.
        4984                 :  * This way the result always represents the valid UTF-8 sequence.
        4985                 :  */
        4986                 : JS_PUBLIC_API(size_t)
        4987                 : JS_EncodeStringToBuffer(JSString *str, char *buffer, size_t length);
        4988                 :
        4989                 : #ifdef __cplusplus
        4990                 :
        4991                 : class JSAutoByteString {
        4992                 :   public:
        4993            1809 :     JSAutoByteString(JSContext *cx, JSString *str JS_GUARD_OBJECT_NOTIFIER_PARAM)
        4994            1809 :       : mBytes(JS_EncodeString(cx, str)) {
        4995            1809 :         JS_ASSERT(cx);
        4996            1809 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        4997            1809 :     }
        4998                 :
        4999           44540 :     JSAutoByteString(JS_GUARD_OBJECT_NOTIFIER_PARAM0)
        5000           44540 :       : mBytes(NULL) {
        5001           44540 :         JS_GUARD_OBJECT_NOTIFIER_INIT;
        5002           44540 :     }
        5003                 :
        5004           92698 :     ~JSAutoByteString() {
        5005           46349 :         js::UnwantedForeground::free_(mBytes);
        5006           46349 :     }
        5007                 :
        5008                 :     /* Take ownership of the given byte array. */
        5009           18450 :     void initBytes(char *bytes) {
        5010           18450 :         JS_ASSERT(!mBytes);
        5011           18450 :         mBytes = bytes;
        5012           18450 :     }
        5013                 :
        5014           24898 :     char *encode(JSContext *cx, JSString *str) {
        5015           24898 :         JS_ASSERT(!mBytes);
        5016           24898 :         JS_ASSERT(cx);
        5017           24898 :         mBytes = JS_EncodeString(cx, str);
        5018           24898 :         return mBytes;
        5019                 :     }
        5020                 :
        5021                 :     void clear() {
        5022                 :         js::UnwantedForeground::free_(mBytes);
        5023                 :         mBytes = NULL;
        5024                 :     }
        5025                 :
        5026           51625 :     char *ptr() const {
        5027           51625 :         return mBytes;
        5028                 :     }
        5029                 :
        5030            1809 :     bool operator!() const {
        5031            1809 :         return !mBytes;
        5032                 :     }
        5033                 :
        5034                 :   private:
        5035                 :     char        *mBytes;
        5036                 :     JS_DECL_USE_GUARD_OBJECT_NOTIFIER
        5037                 :
        5038                 :     /* Copy and assignment are not supported. */
        5039                 :     JSAutoByteString(const JSAutoByteString &another);
        5040                 :     JSAutoByteString &operator=(const JSAutoByteString &another);
        5041                 : };
        5042                 :
        5043                 : #endif
        5044                 :
        5045                 : /************************************************************************/
        5046                 : /*
        5047                 :  * JSON functions
        5048                 :  */
        5049                 : typedef JSBool (* JSONWriteCallback)(const jschar *buf, uint32_t len, void *data);
        5050                 :
        5051                 : /*
        5052                 :  * JSON.stringify as specified by ES5.
        5053                 :  */
        5054                 : JS_PUBLIC_API(JSBool)
        5055                 : JS_Stringify(JSContext *cx, jsval *vp, JSObject *replacer, jsval space,
        5056                 :              JSONWriteCallback callback, void *data);
        5057                 :
        5058                 : /*
        5059                 :  * JSON.parse as specified by ES5.
        5060                 :  */
        5061                 : JS_PUBLIC_API(JSBool)
        5062                 : JS_ParseJSON(JSContext *cx, const jschar *chars, uint32_t len, jsval *vp);
        5063                 :
        5064                 : JS_PUBLIC_API(JSBool)
        5065                 : JS_ParseJSONWithReviver(JSContext *cx, const jschar *chars, uint32_t len, jsval reviver,
        5066                 :                         jsval *vp);
        5067                 :
        5068                 : /************************************************************************/
        5069                 :
        5070                 : /* API for the HTML5 internal structured cloning algorithm. */
        5071                 :
        5072                 : /* The maximum supported structured-clone serialization format version. */
        5073                 : #define JS_STRUCTURED_CLONE_VERSION 1
        5074                 :
        5075                 : struct JSStructuredCloneCallbacks {
        5076                 :     ReadStructuredCloneOp read;
        5077                 :     WriteStructuredCloneOp write;
        5078                 :     StructuredCloneErrorOp reportError;
        5079                 : };
        5080                 :
        5081                 : JS_PUBLIC_API(JSBool)
        5082                 : JS_ReadStructuredClone(JSContext *cx, const uint64_t *data, size_t nbytes,
        5083                 :                        uint32_t version, jsval *vp,
        5084                 :                        const JSStructuredCloneCallbacks *optionalCallbacks,
        5085                 :                        void *closure);
        5086                 :
        5087                 : /* Note: On success, the caller is responsible for calling js::Foreground::free(*datap). */
        5088                 : JS_PUBLIC_API(JSBool)
        5089                 : JS_WriteStructuredClone(JSContext *cx, jsval v, uint64_t **datap, size_t *nbytesp,
        5090                 :                         const JSStructuredCloneCallbacks *optionalCallbacks,
        5091                 :                         void *closure);
        5092                 :
        5093                 : JS_PUBLIC_API(JSBool)
        5094                 : JS_StructuredClone(JSContext *cx, jsval v, jsval *vp,
        5095                 :                    const JSStructuredCloneCallbacks *optionalCallbacks,
        5096                 :                    void *closure);
        5097                 :
        5098                 : #ifdef __cplusplus
        5099                 : JS_END_EXTERN_C
        5100                 :
        5101                 : /* RAII sugar for JS_WriteStructuredClone. */
        5102                 : class JS_PUBLIC_API(JSAutoStructuredCloneBuffer) {
        5103                 :     uint64_t *data_;
        5104                 :     size_t nbytes_;
        5105                 :     uint32_t version_;
        5106                 :
        5107                 :   public:
        5108               0 :     JSAutoStructuredCloneBuffer()
        5109               0 :         : data_(NULL), nbytes_(0), version_(JS_STRUCTURED_CLONE_VERSION) {}
        5110                 :
        5111               0 :     ~JSAutoStructuredCloneBuffer() { clear(); }
        5112                 :
        5113                 :     uint64_t *data() const { return data_; }
        5114                 :     size_t nbytes() const { return nbytes_; }
        5115                 :
        5116                 :     void clear();
        5117                 :
        5118                 :     /* Copy some memory. It will be automatically freed by the destructor. */
        5119                 :     bool copy(const uint64_t *data, size_t nbytes, uint32_t version=JS_STRUCTURED_CLONE_VERSION);
        5120                 :
        5121                 :     /*
        5122                 :      * Adopt some memory. It will be automatically freed by the destructor.
        5123                 :      * data must have been allocated by the JS engine (e.g., extracted via
        5124                 :      * JSAutoStructuredCloneBuffer::steal).
        5125                 :      */
        5126                 :     void adopt(uint64_t *data, size_t nbytes, uint32_t version=JS_STRUCTURED_CLONE_VERSION);
        5127                 :
        5128                 :     /*
        5129                 :      * Remove the buffer so that it will not be automatically freed.
        5130                 :      * After this, the caller is responsible for feeding the memory back to
        5131                 :      * JSAutoStructuredCloneBuffer::adopt.
        5132                 :      */
        5133                 :     void steal(uint64_t **datap, size_t *nbytesp, uint32_t *versionp=NULL);
        5134                 :
        5135                 :     bool read(JSContext *cx, jsval *vp,
        5136                 :               const JSStructuredCloneCallbacks *optionalCallbacks=NULL,
        5137                 :               void *closure=NULL) const;
        5138                 :
        5139                 :     bool write(JSContext *cx, jsval v,
        5140                 :                const JSStructuredCloneCallbacks *optionalCallbacks=NULL,
        5141                 :                void *closure=NULL);
        5142                 :
        5143                 :     /**
        5144                 :      * Swap ownership with another JSAutoStructuredCloneBuffer.
        5145                 :      */
        5146                 :     void swap(JSAutoStructuredCloneBuffer &other);
        5147                 :
        5148                 :   private:
        5149                 :     /* Copy and assignment are not supported. */
        5150                 :     JSAutoStructuredCloneBuffer(const JSAutoStructuredCloneBuffer &other);
        5151                 :     JSAutoStructuredCloneBuffer &operator=(const JSAutoStructuredCloneBuffer &other);
        5152                 : };
        5153                 :
        5154                 : JS_BEGIN_EXTERN_C
        5155                 : #endif
        5156                 :
        5157                 : /* API for implementing custom serialization behavior (for ImageData, File, etc.) */
        5158                 :
        5159                 : /* The range of tag values the application may use for its own custom object types. */
        5160                 : #define JS_SCTAG_USER_MIN  ((uint32_t) 0xFFFF8000)
        5161                 : #define JS_SCTAG_USER_MAX  ((uint32_t) 0xFFFFFFFF)
        5162                 :
        5163                 : #define JS_SCERR_RECURSION 0
        5164                 :
        5165                 : JS_PUBLIC_API(void)
        5166                 : JS_SetStructuredCloneCallbacks(JSRuntime *rt, const JSStructuredCloneCallbacks *callbacks);
        5167                 :
        5168                 : JS_PUBLIC_API(JSBool)
        5169                 : JS_ReadUint32Pair(JSStructuredCloneReader *r, uint32_t *p1, uint32_t *p2);
        5170                 :
        5171                 : JS_PUBLIC_API(JSBool)
        5172                 : JS_ReadBytes(JSStructuredCloneReader *r, void *p, size_t len);
        5173                 :
        5174                 : JS_PUBLIC_API(JSBool)
        5175                 : JS_WriteUint32Pair(JSStructuredCloneWriter *w, uint32_t tag, uint32_t data);
        5176                 :
        5177                 : JS_PUBLIC_API(JSBool)
        5178                 : JS_WriteBytes(JSStructuredCloneWriter *w, const void *p, size_t len);
        5179                 :
        5180                 : /************************************************************************/
        5181                 :
        5182                 : /*
        5183                 :  * Locale specific string conversion and error message callbacks.
        5184                 :  */
        5185                 : struct JSLocaleCallbacks {
        5186                 :     JSLocaleToUpperCase     localeToUpperCase;
        5187                 :     JSLocaleToLowerCase     localeToLowerCase;
        5188                 :     JSLocaleCompare         localeCompare;
        5189                 :     JSLocaleToUnicode       localeToUnicode;
        5190                 :     JSErrorCallback         localeGetErrorMessage;
        5191                 : };
        5192                 :
        5193                 : /*
        5194                 :  * Establish locale callbacks. The pointer must persist as long as the
        5195                 :  * JSContext.  Passing NULL restores the default behaviour.
        5196                 :  */
        5197                 : extern JS_PUBLIC_API(void)
        5198                 : JS_SetLocaleCallbacks(JSContext *cx, JSLocaleCallbacks *callbacks);
        5199                 :
        5200                 : /*
        5201                 :  * Return the address of the current locale callbacks struct, which may
        5202                 :  * be NULL.
        5203                 :  */
        5204                 : extern JS_PUBLIC_API(JSLocaleCallbacks *)
        5205                 : JS_GetLocaleCallbacks(JSContext *cx);
        5206                 :
        5207                 : /************************************************************************/
        5208                 :
        5209                 : /*
        5210                 :  * Error reporting.
        5211                 :  */
        5212                 :
        5213                 : /*
        5214                 :  * Report an exception represented by the sprintf-like conversion of format
        5215                 :  * and its arguments.  This exception message string is passed to a pre-set
        5216                 :  * JSErrorReporter function (set by JS_SetErrorReporter).
        5217                 :  */
        5218                 : extern JS_PUBLIC_API(void)
        5219                 : JS_ReportError(JSContext *cx, const char *format, ...);
        5220                 :
        5221                 : /*
        5222                 :  * Use an errorNumber to retrieve the format string, args are char *
        5223                 :  */
        5224                 : extern JS_PUBLIC_API(void)
        5225                 : JS_ReportErrorNumber(JSContext *cx, JSErrorCallback errorCallback,
        5226                 :                      void *userRef, const unsigned errorNumber, ...);
        5227                 :
        5228                 : /*
        5229                 :  * Use an errorNumber to retrieve the format string, args are jschar *
        5230                 :  */
        5231                 : extern JS_PUBLIC_API(void)
        5232                 : JS_ReportErrorNumberUC(JSContext *cx, JSErrorCallback errorCallback,
        5233                 :                      void *userRef, const unsigned errorNumber, ...);
        5234                 :
        5235                 : /*
        5236                 :  * As above, but report a warning instead (JSREPORT_IS_WARNING(report.flags)).
        5237                 :  * Return true if there was no error trying to issue the warning, and if the
        5238                 :  * warning was not converted into an error due to the JSOPTION_WERROR option
        5239                 :  * being set, false otherwise.
        5240                 :  */
        5241                 : extern JS_PUBLIC_API(JSBool)
        5242                 : JS_ReportWarning(JSContext *cx, const char *format, ...);
        5243                 :
        5244                 : extern JS_PUBLIC_API(JSBool)
        5245                 : JS_ReportErrorFlagsAndNumber(JSContext *cx, unsigned flags,
        5246                 :                              JSErrorCallback errorCallback, void *userRef,
        5247                 :                              const unsigned errorNumber, ...);
        5248                 :
        5249                 : extern JS_PUBLIC_API(JSBool)
        5250                 : JS_ReportErrorFlagsAndNumberUC(JSContext *cx, unsigned flags,
        5251                 :                                JSErrorCallback errorCallback, void *userRef,
        5252                 :                                const unsigned errorNumber, ...);
        5253                 :
        5254                 : /*
        5255                 :  * Complain when out of memory.
        5256                 :  */
        5257                 : extern JS_PUBLIC_API(void)
        5258                 : JS_ReportOutOfMemory(JSContext *cx);
        5259                 :
        5260                 : /*
        5261                 :  * Complain when an allocation size overflows the maximum supported limit.
        5262                 :  */
        5263                 : extern JS_PUBLIC_API(void)
        5264                 : JS_ReportAllocationOverflow(JSContext *cx);
        5265                 :
        5266                 : struct JSErrorReport {
        5267                 :     const char      *filename;      /* source file name, URL, etc., or null */
        5268                 :     JSPrincipals    *originPrincipals; /* see 'originPrincipals' comment above */
        5269                 :     unsigned           lineno;         /* source line number */
        5270                 :     const char      *linebuf;       /* offending source line without final \n */
        5271                 :     const char      *tokenptr;      /* pointer to error token in linebuf */
        5272                 :     const jschar    *uclinebuf;     /* unicode (original) line buffer */
        5273                 :     const jschar    *uctokenptr;    /* unicode (original) token pointer */
        5274                 :     unsigned           flags;          /* error/warning, etc. */
        5275                 :     unsigned           errorNumber;    /* the error number, e.g. see js.msg */
        5276                 :     const jschar    *ucmessage;     /* the (default) error message */
        5277                 :     const jschar    **messageArgs;  /* arguments for the error message */
        5278                 : };
        5279                 :
        5280                 : /*
        5281                 :  * JSErrorReport flag values.  These may be freely composed.
        5282                 :  */
        5283                 : #define JSREPORT_ERROR      0x0     /* pseudo-flag for default case */
        5284                 : #define JSREPORT_WARNING    0x1     /* reported via JS_ReportWarning */
        5285                 : #define JSREPORT_EXCEPTION  0x2     /* exception was thrown */
        5286                 : #define JSREPORT_STRICT     0x4     /* error or warning due to strict option */
        5287                 :
        5288                 : /*
        5289                 :  * This condition is an error in strict mode code, a warning if
        5290                 :  * JS_HAS_STRICT_OPTION(cx), and otherwise should not be reported at
        5291                 :  * all.  We check the strictness of the context's top frame's script;
        5292                 :  * where that isn't appropriate, the caller should do the right checks
        5293                 :  * itself instead of using this flag.
        5294                 :  */
        5295                 : #define JSREPORT_STRICT_MODE_ERROR 0x8
        5296                 :
        5297                 : /*
        5298                 :  * If JSREPORT_EXCEPTION is set, then a JavaScript-catchable exception
        5299                 :  * has been thrown for this runtime error, and the host should ignore it.
        5300                 :  * Exception-aware hosts should also check for JS_IsExceptionPending if
        5301                 :  * JS_ExecuteScript returns failure, and signal or propagate the exception, as
        5302                 :  * appropriate.
        5303                 :  */
        5304                 : #define JSREPORT_IS_WARNING(flags)      (((flags) & JSREPORT_WARNING) != 0)
        5305                 : #define JSREPORT_IS_EXCEPTION(flags)    (((flags) & JSREPORT_EXCEPTION) != 0)
        5306                 : #define JSREPORT_IS_STRICT(flags)       (((flags) & JSREPORT_STRICT) != 0)
        5307                 : #define JSREPORT_IS_STRICT_MODE_ERROR(flags) (((flags) &                      \
        5308                 :                                               JSREPORT_STRICT_MODE_ERROR) != 0)
        5309                 : extern JS_PUBLIC_API(JSErrorReporter)
        5310                 : JS_GetErrorReporter(JSContext *cx);
        5311                 :
        5312                 : extern JS_PUBLIC_API(JSErrorReporter)
        5313                 : JS_SetErrorReporter(JSContext *cx, JSErrorReporter er);
        5314                 :
        5315                 : /************************************************************************/
        5316                 :
        5317                 : /*
        5318                 :  * Dates.
        5319                 :  */
        5320                 :
        5321                 : extern JS_PUBLIC_API(JSObject *)
        5322                 : JS_NewDateObject(JSContext *cx, int year, int mon, int mday, int hour, int min, int sec);
        5323                 :
        5324                 : extern JS_PUBLIC_API(JSObject *)
        5325                 : JS_NewDateObjectMsec(JSContext *cx, double msec);
        5326                 :
        5327                 : /*
        5328                 :  * Infallible predicate to test whether obj is a date object.
        5329                 :  */
        5330                 : extern JS_PUBLIC_API(JSBool)
        5331                 : JS_ObjectIsDate(JSContext *cx, JSObject *obj);
        5332                 :
        5333                 : /************************************************************************/
        5334                 :
        5335                 : /*
        5336                 :  * Regular Expressions.
        5337                 :  */
        5338                 : #define JSREG_FOLD      0x01    /* fold uppercase to lowercase */
        5339                 : #define JSREG_GLOB      0x02    /* global exec, creates array of matches */
        5340                 : #define JSREG_MULTILINE 0x04    /* treat ^ and $ as begin and end of line */
        5341                 : #define JSREG_STICKY    0x08    /* only match starting at lastIndex */
        5342                 :
        5343                 : extern JS_PUBLIC_API(JSObject *)
        5344                 : JS_NewRegExpObject(JSContext *cx, JSObject *obj, char *bytes, size_t length, unsigned flags);
        5345                 :
        5346                 : extern JS_PUBLIC_API(JSObject *)
        5347                 : JS_NewUCRegExpObject(JSContext *cx, JSObject *obj, jschar *chars, size_t length, unsigned flags);
        5348                 :
        5349                 : extern JS_PUBLIC_API(void)
        5350                 : JS_SetRegExpInput(JSContext *cx, JSObject *obj, JSString *input, JSBool multiline);
        5351                 :
        5352                 : extern JS_PUBLIC_API(void)
        5353                 : JS_ClearRegExpStatics(JSContext *cx, JSObject *obj);
        5354                 :
        5355                 : extern JS_PUBLIC_API(JSBool)
        5356                 : JS_ExecuteRegExp(JSContext *cx, JSObject *obj, JSObject *reobj, jschar *chars, size_t length,
        5357                 :                  size_t *indexp, JSBool test, jsval *rval);
        5358                 :
        5359                 : /* RegExp interface for clients without a global object. */
        5360                 :
        5361                 : extern JS_PUBLIC_API(JSObject *)
        5362                 : JS_NewRegExpObjectNoStatics(JSContext *cx, char *bytes, size_t length, unsigned flags);
        5363                 :
        5364                 : extern JS_PUBLIC_API(JSObject *)
        5365                 : JS_NewUCRegExpObjectNoStatics(JSContext *cx, jschar *chars, size_t length, unsigned flags);
        5366                 :
        5367                 : extern JS_PUBLIC_API(JSBool)
        5368                 : JS_ExecuteRegExpNoStatics(JSContext *cx, JSObject *reobj, jschar *chars, size_t length,
        5369                 :                           size_t *indexp, JSBool test, jsval *rval);
        5370                 :
        5371                 : extern JS_PUBLIC_API(JSBool)
        5372                 : JS_ObjectIsRegExp(JSContext *cx, JSObject *obj);
        5373                 :
        5374                 : extern JS_PUBLIC_API(unsigned)
        5375                 : JS_GetRegExpFlags(JSContext *cx, JSObject *obj);
        5376                 :
        5377                 : extern JS_PUBLIC_API(JSString *)
        5378                 : JS_GetRegExpSource(JSContext *cx, JSObject *obj);
        5379                 :
        5380                 : /************************************************************************/
        5381                 :
        5382                 : extern JS_PUBLIC_API(JSBool)
        5383                 : JS_IsExceptionPending(JSContext *cx);
        5384                 :
        5385                 : extern JS_PUBLIC_API(JSBool)
        5386                 : JS_GetPendingException(JSContext *cx, jsval *vp);
        5387                 :
        5388                 : extern JS_PUBLIC_API(void)
        5389                 : JS_SetPendingException(JSContext *cx, jsval v);
        5390                 :
        5391                 : extern JS_PUBLIC_API(void)
        5392                 : JS_ClearPendingException(JSContext *cx);
        5393                 :
        5394                 : extern JS_PUBLIC_API(JSBool)
        5395                 : JS_ReportPendingException(JSContext *cx);
        5396                 :
        5397                 : /*
        5398                 :  * Save the current exception state.  This takes a snapshot of cx's current
        5399                 :  * exception state without making any change to that state.
        5400                 :  *
        5401                 :  * The returned state pointer MUST be passed later to JS_RestoreExceptionState
        5402                 :  * (to restore that saved state, overriding any more recent state) or else to
        5403                 :  * JS_DropExceptionState (to free the state struct in case it is not correct
        5404                 :  * or desirable to restore it).  Both Restore and Drop free the state struct,
        5405                 :  * so callers must stop using the pointer returned from Save after calling the
        5406                 :  * Release or Drop API.
        5407                 :  */
        5408                 : extern JS_PUBLIC_API(JSExceptionState *)
        5409                 : JS_SaveExceptionState(JSContext *cx);
        5410                 :
        5411                 : extern JS_PUBLIC_API(void)
        5412                 : JS_RestoreExceptionState(JSContext *cx, JSExceptionState *state);
        5413                 :
        5414                 : extern JS_PUBLIC_API(void)
        5415                 : JS_DropExceptionState(JSContext *cx, JSExceptionState *state);
        5416                 :
        5417                 : /*
        5418                 :  * If the given value is an exception object that originated from an error,
        5419                 :  * the exception will contain an error report struct, and this API will return
        5420                 :  * the address of that struct.  Otherwise, it returns NULL.  The lifetime of
        5421                 :  * the error report struct that might be returned is the same as the lifetime
        5422                 :  * of the exception object.
        5423                 :  */
        5424                 : extern JS_PUBLIC_API(JSErrorReport *)
        5425                 : JS_ErrorFromException(JSContext *cx, jsval v);
        5426                 :
        5427                 : /*
        5428                 :  * Given a reported error's message and JSErrorReport struct pointer, throw
        5429                 :  * the corresponding exception on cx.
        5430                 :  */
        5431                 : extern JS_PUBLIC_API(JSBool)
        5432                 : JS_ThrowReportedError(JSContext *cx, const char *message,
        5433                 :                       JSErrorReport *reportp);
        5434                 :
        5435                 : /*
        5436                 :  * Throws a StopIteration exception on cx.
        5437                 :  */
        5438                 : extern JS_PUBLIC_API(JSBool)
        5439                 : JS_ThrowStopIteration(JSContext *cx);
        5440                 :
        5441                 : extern JS_PUBLIC_API(intptr_t)
        5442                 : JS_GetCurrentThread();
        5443                 :
        5444                 : /*
        5445                 :  * A JS runtime always has an "owner thread". The owner thread is set when the
        5446                 :  * runtime is created (to the current thread) and practically all entry points
        5447                 :  * into the JS engine check that a runtime (or anything contained in the
        5448                 :  * runtime: context, compartment, object, etc) is only touched by its owner
        5449                 :  * thread. Embeddings may check this invariant outside the JS engine by calling
        5450                 :  * JS_AbortIfWrongThread (which will abort if not on the owner thread, even for
        5451                 :  * non-debug builds).
        5452                 :  *
        5453                 :  * It is possible to "move" a runtime between threads. This is accomplished by
        5454                 :  * calling JS_ClearRuntimeThread on a runtime's owner thread and then calling
        5455                 :  * JS_SetRuntimeThread on the new owner thread. The runtime must not be
        5456                 :  * accessed between JS_ClearRuntimeThread and JS_SetRuntimeThread. Also, the
        5457                 :  * caller is responsible for synchronizing the calls to Set/Clear.
        5458                 :  */
        5459                 :
        5460                 : extern JS_PUBLIC_API(void)
        5461                 : JS_AbortIfWrongThread(JSRuntime *rt);
        5462                 :
        5463                 : extern JS_PUBLIC_API(void)
        5464                 : JS_ClearRuntimeThread(JSRuntime *rt);
        5465                 :
        5466                 : extern JS_PUBLIC_API(void)
        5467                 : JS_SetRuntimeThread(JSRuntime *rt);
        5468                 :
        5469                 : #ifdef __cplusplus
        5470                 : JS_END_EXTERN_C
        5471                 :
        5472                 : class JSAutoSetRuntimeThread
        5473                 : {
        5474                 :     JSRuntime *runtime;
        5475                 :
        5476                 :   public:
        5477               0 :     JSAutoSetRuntimeThread(JSRuntime *runtime) : runtime(runtime) {
        5478               0 :         JS_SetRuntimeThread(runtime);
        5479               0 :     }
        5480                 :
        5481               0 :     ~JSAutoSetRuntimeThread() {
        5482               0 :         JS_ClearRuntimeThread(runtime);
        5483               0 :     }
        5484                 : };
        5485                 :
        5486                 : JS_BEGIN_EXTERN_C
        5487                 : #endif
        5488                 :
        5489                 : /************************************************************************/
        5490                 :
        5491                 : /*
        5492                 :  * JS_IsConstructing must be called from within a native given the
        5493                 :  * native's original cx and vp arguments. If JS_IsConstructing is true,
        5494                 :  * JS_THIS must not be used; the constructor should construct and return a
        5495                 :  * new object. Otherwise, the native is called as an ordinary function and
        5496                 :  * JS_THIS may be used.
        5497                 :  */
        5498                 : static JS_ALWAYS_INLINE JSBool
        5499               1 : JS_IsConstructing(JSContext *cx, const jsval *vp)
        5500                 : {
        5501                 : #ifdef DEBUG
        5502               1 :     JSObject *callee = JSVAL_TO_OBJECT(JS_CALLEE(cx, vp));
        5503               1 :     if (JS_ObjectIsFunction(cx, callee)) {
        5504               0 :         JSFunction *fun = JS_ValueToFunction(cx, JS_CALLEE(cx, vp));
        5505               0 :         JS_ASSERT((JS_GetFunctionFlags(fun) & JSFUN_CONSTRUCTOR) != 0);
        5506                 :     } else {
        5507               1 :         JS_ASSERT(JS_GetClass(callee)->construct != NULL);
        5508                 :     }
        5509                 : #else
        5510                 :     (void)cx;
        5511                 : #endif
        5512                 :
        5513               1 :     return JSVAL_IS_MAGIC_IMPL(JSVAL_TO_IMPL(vp[1]));
        5514                 : }
        5515                 :
        5516                 : /*
        5517                 :  * A constructor can request that the JS engine create a default new 'this'
        5518                 :  * object of the given class, using the callee to determine parentage and
        5519                 :  * [[Prototype]].
        5520                 :  */
        5521                 : extern JS_PUBLIC_API(JSObject *)
        5522                 : JS_NewObjectForConstructor(JSContext *cx, JSClass *clasp, const jsval *vp);
        5523                 :
        5524                 : /************************************************************************/
        5525                 :
        5526                 : #ifdef DEBUG
        5527                 : #define JS_GC_ZEAL 1
        5528                 : #endif
        5529                 :
        5530                 : #ifdef JS_GC_ZEAL
        5531                 : #define JS_DEFAULT_ZEAL_FREQ 100
        5532                 :
        5533                 : extern JS_PUBLIC_API(void)
        5534                 : JS_SetGCZeal(JSContext *cx, uint8_t zeal, uint32_t frequency);
        5535                 :
        5536                 : extern JS_PUBLIC_API(void)
        5537                 : JS_ScheduleGC(JSContext *cx, uint32_t count);
        5538                 : #endif
        5539                 :
        5540                 : /*
        5541                 :  * Convert a uint32_t index into a jsid.
        5542                 :  */
        5543                 : extern JS_PUBLIC_API(JSBool)
        5544                 : JS_IndexToId(JSContext *cx, uint32_t index, jsid *id);
        5545                 :
        5546                 : /*
        5547                 :  *  Test if the given string is a valid ECMAScript identifier
        5548                 :  */
        5549                 : extern JS_PUBLIC_API(JSBool)
        5550                 : JS_IsIdentifier(JSContext *cx, JSString *str, JSBool *isIdentifier);
        5551                 :
        5552                 : /*
        5553                 :  * Return the current script and line number of the most currently running
        5554                 :  * frame. Returns true if a scripted frame was found, false otherwise.
        5555                 :  */
        5556                 : extern JS_PUBLIC_API(JSBool)
        5557                 : JS_DescribeScriptedCaller(JSContext *cx, JSScript **script, unsigned *lineno);
        5558                 :
        5559                 :
        5560                 : /*
        5561                 :  * Encode/Decode interpreted scripts and functions to/from memory.
        5562                 :  */
        5563                 :
        5564                 : extern JS_PUBLIC_API(void *)
        5565                 : JS_EncodeScript(JSContext *cx, JSScript *script, uint32_t *lengthp);
        5566                 :
        5567                 : extern JS_PUBLIC_API(void *)
        5568                 : JS_EncodeInterpretedFunction(JSContext *cx, JSObject *funobj, uint32_t *lengthp);
        5569                 :
        5570                 : extern JS_PUBLIC_API(JSScript *)
        5571                 : JS_DecodeScript(JSContext *cx, const void *data, uint32_t length,
        5572                 :                 JSPrincipals *principals, JSPrincipals *originPrincipals);
        5573                 :
        5574                 : extern JS_PUBLIC_API(JSObject *)
        5575                 : JS_DecodeInterpretedFunction(JSContext *cx, const void *data, uint32_t length,
        5576                 :                              JSPrincipals *principals, JSPrincipals *originPrincipals);
        5577                 :
        5578                 : JS_END_EXTERN_C
        5579                 :
        5580                 : #endif /* jsapi_h___ */

Generated by: LCOV version 1.7