js/public/Utility.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=8 sw=4 et tw=99 ft=cpp:
   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 SpiderMonkey JavaScript code.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * the Mozilla Foundation.
  21  * Portions created by the Initial Developer are Copyright (C) 2011
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #ifndef js_utility_h__
  41 #define js_utility_h__
  42
  43 #include <stdlib.h>
  44 #include <string.h>
  45
  46 #include "mozilla/Util.h"
  47
  48 #ifdef __cplusplus
  49
  50 /* The public JS engine namespace. */
  51 namespace JS {}
  52
  53 /* The mozilla-shared reusable template/utility namespace. */
  54 namespace mozilla {}
  55
  56 /* The private JS engine namespace. */
  57 namespace js {
  58
  59 /* The private namespace is a superset of the public/shared namespaces. */
  60 using namespace JS;
  61 using namespace mozilla;
  62
  63 }  /* namespace js */
  64 #endif  /* __cplusplus */
  65
  66 JS_BEGIN_EXTERN_C
  67
  68 /*
  69  * Pattern used to overwrite freed memory. If you are accessing an object with
  70  * this pattern, you probably have a dangling pointer.
  71  */
  72 #define JS_FREE_PATTERN 0xDA
  73
  74 /* JS_ASSERT */
  75 #ifdef DEBUG
  76 # define JS_ASSERT(expr)                                                      \
  77     ((expr) ? (void)0 : JS_Assert(#expr, __FILE__, __LINE__))
  78 # define JS_ASSERT_IF(cond, expr)                                             \
  79     ((!(cond) || (expr)) ? (void)0 : JS_Assert(#expr, __FILE__, __LINE__))
  80 # define JS_NOT_REACHED(reason)                                               \
  81     JS_Assert(reason, __FILE__, __LINE__)
  82 # define JS_ALWAYS_TRUE(expr) JS_ASSERT(expr)
  83 # define JS_ALWAYS_FALSE(expr) JS_ASSERT(!(expr))
  84 # ifdef JS_THREADSAFE
  85 #  define JS_THREADSAFE_ASSERT(expr) JS_ASSERT(expr)
  86 # else
  87 #  define JS_THREADSAFE_ASSERT(expr) ((void) 0)
  88 # endif
  89 #else
  90 # define JS_ASSERT(expr)         ((void) 0)
  91 # define JS_ASSERT_IF(cond,expr) ((void) 0)
  92 # define JS_NOT_REACHED(reason)
  93 # define JS_ALWAYS_TRUE(expr)    ((void) (expr))
  94 # define JS_ALWAYS_FALSE(expr)    ((void) (expr))
  95 # define JS_THREADSAFE_ASSERT(expr) ((void) 0)
  96 #endif
  97
  98 /*
  99  * JS_STATIC_ASSERT
 100  *
 101  * A compile-time assert. "cond" must be a constant expression. The macro can
 102  * be used only in places where an "extern" declaration is allowed.
 103  */
 104 #ifdef __SUNPRO_CC
 105 /*
 106  * Sun Studio C++ compiler has a bug
 107  * "sizeof expression not accepted as size of array parameter"
 108  * It happens when js_static_assert() function is declared inside functions.
 109  * The bug number is 6688515. It is not public yet.
 110  * Therefore, for Sun Studio, declare js_static_assert as an array instead.
 111  */
 112 # define JS_STATIC_ASSERT(cond) extern char js_static_assert[(cond) ? 1 : -1]
 113 #else
 114 # ifdef __COUNTER__
 115 #  define JS_STATIC_ASSERT_GLUE1(x,y) x##y
 116 #  define JS_STATIC_ASSERT_GLUE(x,y) JS_STATIC_ASSERT_GLUE1(x,y)
 117 #  define JS_STATIC_ASSERT(cond)                                            \
 118         typedef int JS_STATIC_ASSERT_GLUE(js_static_assert, __COUNTER__)[(cond) ? 1 : -1]
 119 # else
 120 #  define JS_STATIC_ASSERT(cond) extern void js_static_assert(int arg[(cond) ? 1 : -1])
 121 # endif
 122 #endif
 123
 124 #define JS_STATIC_ASSERT_IF(cond, expr) JS_STATIC_ASSERT(!(cond) || (expr))
 125
 126 /*
 127  * Abort the process in a non-graceful manner. This will cause a core file,
 128  * call to the debugger or other moral equivalent as well as causing the
 129  * entire process to stop.
 130  */
 131 extern JS_PUBLIC_API(void) JS_Abort(void);
 132
 133 /*
 134  * Custom allocator support for SpiderMonkey
 135  */
 136 #if defined JS_USE_CUSTOM_ALLOCATOR
 137 # include "jscustomallocator.h"
 138 #else
 139 # ifdef DEBUG
 140 /*
 141  * In order to test OOM conditions, when the shell command-line option
 142  * |-A NUM| is passed, we fail continuously after the NUM'th allocation.
 143  */
 144 extern JS_PUBLIC_DATA(JSUint32) OOM_maxAllocations; /* set from shell/js.cpp */
 145 extern JS_PUBLIC_DATA(JSUint32) OOM_counter; /* data race, who cares. */
 146 #  define JS_OOM_POSSIBLY_FAIL() \
 147     do \
 148     { \
 149         if (OOM_counter++ >= OOM_maxAllocations) { \
 150             return NULL; \
 151         } \
 152     } while (0)
 153
 154 # else
 155 #  define JS_OOM_POSSIBLY_FAIL() do {} while(0)
 156 # endif
 157
 158 /*
 159  * SpiderMonkey code should not be calling these allocation functions directly.
 160  * Instead, all calls should go through JSRuntime, JSContext or OffTheBooks.
 161  * However, js_free() can be called directly.
 162  */
 163 static JS_INLINE void* js_malloc(size_t bytes)
 164 {
 165     JS_OOM_POSSIBLY_FAIL();
 166     return malloc(bytes);
 167 }
 168
 169 static JS_INLINE void* js_calloc(size_t bytes)
 170 {
 171     JS_OOM_POSSIBLY_FAIL();
 172     return calloc(bytes, 1);
 173 }
 174
 175 static JS_INLINE void* js_realloc(void* p, size_t bytes)
 176 {
 177     JS_OOM_POSSIBLY_FAIL();
 178     return realloc(p, bytes);
 179 }
 180
 181 static JS_INLINE void js_free(void* p)
 182 {
 183     free(p);
 184 }
 185 #endif/* JS_USE_CUSTOM_ALLOCATOR */
 186
 187 /*
 188  * Replace bit-scanning code sequences with CPU-specific instructions to
 189  * speedup calculations of ceiling/floor log2.
 190  *
 191  * With GCC 3.4 or later we can use __builtin_clz for that, see bug 327129.
 192  *
 193  * SWS: Added MSVC intrinsic bitscan support.  See bugs 349364 and 356856.
 194  */
 195 #if defined(_WIN32) && (_MSC_VER >= 1300) && (defined(_M_IX86) || defined(_M_AMD64) || defined(_M_X64))
 196
 197 unsigned char _BitScanForward(unsigned long * Index, unsigned long Mask);
 198 unsigned char _BitScanReverse(unsigned long * Index, unsigned long Mask);
 199 # pragma intrinsic(_BitScanForward,_BitScanReverse)
 200
 201 __forceinline static int
 202 __BitScanForward32(unsigned int val)
 203 {
 204     unsigned long idx;
 205
 206     _BitScanForward(&idx, (unsigned long)val);
 207     return (int)idx;
 208 }
 209 __forceinline static int
 210 __BitScanReverse32(unsigned int val)
 211 {
 212     unsigned long idx;
 213
 214     _BitScanReverse(&idx, (unsigned long)val);
 215     return (int)(31-idx);
 216 }
 217 # define js_bitscan_ctz32(val)  __BitScanForward32(val)
 218 # define js_bitscan_clz32(val)  __BitScanReverse32(val)
 219 # define JS_HAS_BUILTIN_BITSCAN32
 220
 221 #if defined(_M_AMD64) || defined(_M_X64)
 222 unsigned char _BitScanForward64(unsigned long * Index, unsigned __int64 Mask);
 223 unsigned char _BitScanReverse64(unsigned long * Index, unsigned __int64 Mask);
 224 # pragma intrinsic(_BitScanForward64,_BitScanReverse64)
 225
 226 __forceinline static int
 227 __BitScanForward64(unsigned __int64 val)
 228 {
 229     unsigned long idx;
 230
 231     _BitScanForward64(&idx, val);
 232     return (int)idx;
 233 }
 234 __forceinline static int
 235 __BitScanReverse64(unsigned __int64 val)
 236 {
 237     unsigned long idx;
 238
 239     _BitScanReverse64(&idx, val);
 240     return (int)(63-idx);
 241 }
 242 # define js_bitscan_ctz64(val)  __BitScanForward64(val)
 243 # define js_bitscan_clz64(val)  __BitScanReverse64(val)
 244 # define JS_HAS_BUILTIN_BITSCAN64
 245 #endif
 246 #elif (__GNUC__ >= 4) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
 247
 248 # define js_bitscan_ctz32(val)  __builtin_ctz(val)
 249 # define js_bitscan_clz32(val)  __builtin_clz(val)
 250 # define JS_HAS_BUILTIN_BITSCAN32
 251 # if (JS_BYTES_PER_WORD == 8)
 252 #  define js_bitscan_ctz64(val)  __builtin_ctzll(val)
 253 #  define js_bitscan_clz64(val)  __builtin_clzll(val)
 254 #  define JS_HAS_BUILTIN_BITSCAN64
 255 # endif
 256
 257 #endif
 258
 259 /*
 260 ** Macro version of JS_CeilingLog2: Compute the log of the least power of
 261 ** 2 greater than or equal to _n. The result is returned in _log2.
 262 */
 263 #ifdef JS_HAS_BUILTIN_BITSCAN32
 264 /*
 265  * Use intrinsic function or count-leading-zeros to calculate ceil(log2(_n)).
 266  * The macro checks for "n <= 1" and not "n != 0" as js_bitscan_clz32(0) is
 267  * undefined.
 268  */
 269 # define JS_CEILING_LOG2(_log2,_n)                                            \
 270     JS_BEGIN_MACRO                                                            \
 271         unsigned int j_ = (unsigned int)(_n);                                 \
 272         (_log2) = (j_ <= 1 ? 0 : 32 - js_bitscan_clz32(j_ - 1));              \
 273     JS_END_MACRO
 274 #else
 275 # define JS_CEILING_LOG2(_log2,_n)                                            \
 276     JS_BEGIN_MACRO                                                            \
 277         JSUint32 j_ = (JSUint32)(_n);                                         \
 278         (_log2) = 0;                                                          \
 279         if ((j_) & ((j_)-1))                                                  \
 280             (_log2) += 1;                                                     \
 281         if ((j_) >> 16)                                                       \
 282             (_log2) += 16, (j_) >>= 16;                                       \
 283         if ((j_) >> 8)                                                        \
 284             (_log2) += 8, (j_) >>= 8;                                         \
 285         if ((j_) >> 4)                                                        \
 286             (_log2) += 4, (j_) >>= 4;                                         \
 287         if ((j_) >> 2)                                                        \
 288             (_log2) += 2, (j_) >>= 2;                                         \
 289         if ((j_) >> 1)                                                        \
 290             (_log2) += 1;                                                     \
 291     JS_END_MACRO
 292 #endif
 293
 294 /*
 295 ** Macro version of JS_FloorLog2: Compute the log of the greatest power of
 296 ** 2 less than or equal to _n. The result is returned in _log2.
 297 **
 298 ** This is equivalent to finding the highest set bit in the word.
 299 */
 300 #ifdef JS_HAS_BUILTIN_BITSCAN32
 301 /*
 302  * Use js_bitscan_clz32 or count-leading-zeros to calculate floor(log2(_n)).
 303  * Since js_bitscan_clz32(0) is undefined, the macro set the loweset bit to 1
 304  * to ensure 0 result when _n == 0.
 305  */
 306 # define JS_FLOOR_LOG2(_log2,_n)                                              \
 307     JS_BEGIN_MACRO                                                            \
 308         (_log2) = 31 - js_bitscan_clz32(((unsigned int)(_n)) | 1);            \
 309     JS_END_MACRO
 310 #else
 311 # define JS_FLOOR_LOG2(_log2,_n)                                              \
 312     JS_BEGIN_MACRO                                                            \
 313         JSUint32 j_ = (JSUint32)(_n);                                         \
 314         (_log2) = 0;                                                          \
 315         if ((j_) >> 16)                                                       \
 316             (_log2) += 16, (j_) >>= 16;                                       \
 317         if ((j_) >> 8)                                                        \
 318             (_log2) += 8, (j_) >>= 8;                                         \
 319         if ((j_) >> 4)                                                        \
 320             (_log2) += 4, (j_) >>= 4;                                         \
 321         if ((j_) >> 2)                                                        \
 322             (_log2) += 2, (j_) >>= 2;                                         \
 323         if ((j_) >> 1)                                                        \
 324             (_log2) += 1;                                                     \
 325     JS_END_MACRO
 326 #endif
 327
 328 /*
 329  * Internal function.
 330  * Compute the log of the least power of 2 greater than or equal to n. This is
 331  * a version of JS_CeilingLog2 that operates on unsigned integers with
 332  * CPU-dependant size.
 333  */
 334 #define JS_CEILING_LOG2W(n) ((n) <= 1 ? 0 : 1 + JS_FLOOR_LOG2W((n) - 1))
 335
 336 /*
 337  * Internal function.
 338  * Compute the log of the greatest power of 2 less than or equal to n.
 339  * This is a version of JS_FloorLog2 that operates on unsigned integers with
 340  * CPU-dependant size and requires that n != 0.
 341  */
 342 #define JS_FLOOR_LOG2W(n) (JS_ASSERT((n) != 0), js_FloorLog2wImpl(n))
 343
 344 #if JS_BYTES_PER_WORD == 4
 345 # ifdef JS_HAS_BUILTIN_BITSCAN32
 346 #  define js_FloorLog2wImpl(n)                                                \
 347     ((size_t)(JS_BITS_PER_WORD - 1 - js_bitscan_clz32(n)))
 348 # else
 349 extern size_t js_FloorLog2wImpl(size_t n);
 350 # endif
 351 #elif JS_BYTES_PER_WORD == 8
 352 # ifdef JS_HAS_BUILTIN_BITSCAN64
 353 #  define js_FloorLog2wImpl(n)                                                \
 354     ((size_t)(JS_BITS_PER_WORD - 1 - js_bitscan_clz64(n)))
 355 # else
 356 extern size_t js_FloorLog2wImpl(size_t n);
 357 # endif
 358 #else
 359 # error "NOT SUPPORTED"
 360 #endif
 361
 362 JS_END_EXTERN_C
 363
 364 #ifdef __cplusplus
 365 #include <new>
 366
 367 /*
 368  * User guide to memory management within SpiderMonkey:
 369  *
 370  * Quick tips:
 371  *
 372  *   Allocation:
 373  *   - Prefer to allocate using JSContext:
 374  *       cx->{malloc_,realloc_,calloc_,new_,array_new}
 375  *
 376  *   - If no JSContext is available, use a JSRuntime:
 377  *       rt->{malloc_,realloc_,calloc_,new_,array_new}
 378  *
 379  *   - As a last resort, use unaccounted allocation ("OffTheBooks"):
 380  *       js::OffTheBooks::{malloc_,realloc_,calloc_,new_,array_new}
 381  *
 382  *   Deallocation:
 383  *   - When the deallocation occurs on a slow path, use:
 384  *       Foreground::{free_,delete_,array_delete}
 385  *
 386  *   - Otherwise deallocate on a background thread using a JSContext:
 387  *       cx->{free_,delete_,array_delete}
 388  *
 389  *   - If no JSContext is available, use a JSRuntime:
 390  *       rt->{free_,delete_,array_delete}
 391  *
 392  *   - As a last resort, use UnwantedForeground deallocation:
 393  *       js::UnwantedForeground::{free_,delete_,array_delete}
 394  *
 395  * General tips:
 396  *
 397  *   - Mixing and matching these allocators is allowed (you may free memory
 398  *     allocated by any allocator, with any deallocator).
 399  *
 400  *   - Never, ever use normal C/C++ memory management:
 401  *       malloc, free, new, new[], delete, operator new, etc.
 402  *
 403  *   - Never, ever use low-level SpiderMonkey allocators:
 404  *       js_malloc(), js_free(), js_calloc(), js_realloc()
 405  *     Their use is reserved for the other memory managers.
 406  *
 407  *   - Classes which have private constructors or destructors should have
 408  *     JS_DECLARE_ALLOCATION_FRIENDS_FOR_PRIVATE_CONSTRUCTOR added to their
 409  *     declaration.
 410  *
 411  * Details:
 412  *
 413  *   Using vanilla new/new[] is unsafe in SpiderMonkey because they throw on
 414  *   failure instead of returning NULL, which is what SpiderMonkey expects.
 415  *   (Even overriding them is unsafe, as the system's C++ runtime library may
 416  *   throw, which we do not support. We also can't just use the 'nothrow'
 417  *   variant of new/new[], because we want to mediate *all* allocations
 418  *   within SpiderMonkey, to satisfy any embedders using
 419  *   JS_USE_CUSTOM_ALLOCATOR.)
 420  *
 421  *   JSContexts and JSRuntimes keep track of memory allocated, and use this
 422  *   accounting to schedule GC. OffTheBooks does not. We'd like to remove
 423  *   OffTheBooks allocations as much as possible (bug 636558).
 424  *
 425  *   On allocation failure, a JSContext correctly reports an error, which a
 426  *   JSRuntime and OffTheBooks does not.
 427  *
 428  *   A JSContext deallocates in a background thread. A JSRuntime might
 429  *   deallocate in the background in the future, but does not now. Foreground
 430  *   deallocation is preferable on slow paths. UnwantedForeground deallocations
 431  *   occur where we have no JSContext or JSRuntime, and the deallocation is not
 432  *   on a slow path. We want to remove UnwantedForeground deallocations (bug
 433  *   636561).
 434  *
 435  *   JS_DECLARE_ALLOCATION_FRIENDS_FOR_PRIVATE_CONSTRUCTOR makes the allocation
 436  *   classes friends with your class, giving them access to private
 437  *   constructors and destructors.
 438  *
 439  *   |make check| does a source level check on the number of uses OffTheBooks,
 440  *   UnwantedForeground, js_malloc, js_free etc, to prevent regressions. If you
 441  *   really must add one, update Makefile.in, and run |make check|.
 442  *
 443  *   |make check| also statically prevents the use of vanilla new/new[].
 444  */
 445
 446 #define JS_NEW_BODY(allocator, t, parms)                                       \
 447     void *memory = allocator(sizeof(t));                                       \
 448     return memory ? new(memory) t parms : NULL;
 449
 450 /*
 451  * Given a class which should provide new_() methods, add
 452  * JS_DECLARE_NEW_METHODS (see JSContext for a usage example). This
 453  * adds new_()s with up to 12 parameters. Add more versions of new_ below if
 454  * you need more than 12 parameters.
 455  *
 456  * Note: Do not add a ; at the end of a use of JS_DECLARE_NEW_METHODS,
 457  * or the build will break.
 458  */
 459 #define JS_DECLARE_NEW_METHODS(ALLOCATOR, QUALIFIERS)\
 460     template <class T>\
 461     QUALIFIERS T *new_() {\
 462         JS_NEW_BODY(ALLOCATOR, T, ())\
 463     }\
 464 \
 465     template <class T, class P1>\
 466     QUALIFIERS T *new_(P1 p1) {\
 467         JS_NEW_BODY(ALLOCATOR, T, (p1))\
 468     }\
 469 \
 470     template <class T, class P1, class P2>\
 471     QUALIFIERS T *new_(P1 p1, P2 p2) {\
 472         JS_NEW_BODY(ALLOCATOR, T, (p1, p2))\
 473     }\
 474 \
 475     template <class T, class P1, class P2, class P3>\
 476     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3) {\
 477         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3))\
 478     }\
 479 \
 480     template <class T, class P1, class P2, class P3, class P4>\
 481     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4) {\
 482         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4))\
 483     }\
 484 \
 485     template <class T, class P1, class P2, class P3, class P4, class P5>\
 486     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4, P5 p5) {\
 487         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4, p5))\
 488     }\
 489 \
 490     template <class T, class P1, class P2, class P3, class P4, class P5, class P6>\
 491     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4, P5 p5, P6 p6) {\
 492         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4, p5, p6))\
 493     }\
 494 \
 495     template <class T, class P1, class P2, class P3, class P4, class P5, class P6, class P7>\
 496     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4, P5 p5, P6 p6, P7 p7) {\
 497         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4, p5, p6, p7))\
 498     }\
 499 \
 500     template <class T, class P1, class P2, class P3, class P4, class P5, class P6, class P7, class P8>\
 501     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4, P5 p5, P6 p6, P7 p7, P8 p8) {\
 502         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4, p5, p6, p7, p8))\
 503     }\
 504 \
 505     template <class T, class P1, class P2, class P3, class P4, class P5, class P6, class P7, class P8, class P9>\
 506     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4, P5 p5, P6 p6, P7 p7, P8 p8, P9 p9) {\
 507         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4, p5, p6, p7, p8, p9))\
 508     }\
 509 \
 510     template <class T, class P1, class P2, class P3, class P4, class P5, class P6, class P7, class P8, class P9, class P10>\
 511     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4, P5 p5, P6 p6, P7 p7, P8 p8, P9 p9, P10 p10) {\
 512         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4, p5, p6, p7, p8, p9, p10))\
 513     }\
 514 \
 515     template <class T, class P1, class P2, class P3, class P4, class P5, class P6, class P7, class P8, class P9, class P10, class P11>\
 516     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4, P5 p5, P6 p6, P7 p7, P8 p8, P9 p9, P10 p10, P11 p11) {\
 517         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11))\
 518     }\
 519 \
 520     template <class T, class P1, class P2, class P3, class P4, class P5, class P6, class P7, class P8, class P9, class P10, class P11, class P12>\
 521     QUALIFIERS T *new_(P1 p1, P2 p2, P3 p3, P4 p4, P5 p5, P6 p6, P7 p7, P8 p8, P9 p9, P10 p10, P11 p11, P12 p12) {\
 522         JS_NEW_BODY(ALLOCATOR, T, (p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12))\
 523     }\
 524     static const int JSMinAlignment = 8;\
 525     template <class T>\
 526     QUALIFIERS T *array_new(size_t n) {\
 527         /* The length is stored just before the vector memory. */\
 528         uint64 numBytes64 = uint64(JSMinAlignment) + uint64(sizeof(T)) * uint64(n);\
 529         size_t numBytes = size_t(numBytes64);\
 530         if (numBytes64 != numBytes) {\
 531             JS_ASSERT(0);   /* we want to know if this happens in debug builds */\
 532             return NULL;\
 533         }\
 534         void *memory = ALLOCATOR(numBytes);\
 535         if (!memory)\
 536             return NULL;\
 537         *(size_t *)memory = n;\
 538         memory = (void*)(uintptr_t(memory) + JSMinAlignment);\
 539         return new(memory) T[n];\
 540     }\
 541
 542
 543 #define JS_DECLARE_DELETE_METHODS(DEALLOCATOR, QUALIFIERS)\
 544     template <class T>\
 545     QUALIFIERS void delete_(T *p) {\
 546         if (p) {\
 547             p->~T();\
 548             DEALLOCATOR(p);\
 549         }\
 550     }\
 551 \
 552     template <class T>\
 553     QUALIFIERS void array_delete(T *p) {\
 554         if (p) {\
 555             void* p0 = (void *)(uintptr_t(p) - js::OffTheBooks::JSMinAlignment);\
 556             size_t n = *(size_t *)p0;\
 557             for (size_t i = 0; i < n; i++)\
 558                 (p + i)->~T();\
 559             DEALLOCATOR(p0);\
 560         }\
 561     }
 562
 563
 564 /*
 565  * In general, all allocations should go through a JSContext or JSRuntime, so
 566  * that the garbage collector knows how much memory has been allocated. In
 567  * cases where it is difficult to use a JSContext or JSRuntime, OffTheBooks can
 568  * be used, though this is undesirable.
 569  */
 570 namespace js {
 571
 572 class OffTheBooks {
 573 public:
 574     JS_DECLARE_NEW_METHODS(::js_malloc, JS_ALWAYS_INLINE static)
 575
 576     static JS_INLINE void* malloc_(size_t bytes) {
 577         return ::js_malloc(bytes);
 578     }
 579
 580     static JS_INLINE void* calloc_(size_t bytes) {
 581         return ::js_calloc(bytes);
 582     }
 583
 584     static JS_INLINE void* realloc_(void* p, size_t bytes) {
 585         return ::js_realloc(p, bytes);
 586     }
 587 };
 588
 589 /*
 590  * We generally prefer deallocating using JSContext because it can happen in
 591  * the background. On slow paths, we may prefer foreground allocation.
 592  */
 593 class Foreground {
 594 public:
 595     /* See parentheses comment above. */
 596     static JS_ALWAYS_INLINE void free_(void* p) {
 597         ::js_free(p);
 598     }
 599
 600     JS_DECLARE_DELETE_METHODS(::js_free, JS_ALWAYS_INLINE static)
 601 };
 602
 603 class UnwantedForeground : public Foreground {
 604 };
 605
 606 } /* namespace js */
 607
 608 /*
 609  * Note lack of ; in JSRuntime below. This is intentional so "calling" this
 610  * looks "normal".
 611  */
 612 #define JS_DECLARE_ALLOCATION_FRIENDS_FOR_PRIVATE_CONSTRUCTOR \
 613     friend class js::OffTheBooks;\
 614     friend class js::Foreground;\
 615     friend class js::UnwantedForeground;\
 616     friend struct ::JSContext;\
 617     friend struct ::JSRuntime
 618
 619 /*
 620  * The following classes are designed to cause assertions to detect
 621  * inadvertent use of guard objects as temporaries.  In other words,
 622  * when we have a guard object whose only purpose is its constructor and
 623  * destructor (and is never otherwise referenced), the intended use
 624  * might be:
 625  *     JSAutoTempValueRooter tvr(cx, 1, &val);
 626  * but is is easy to accidentally write:
 627  *     JSAutoTempValueRooter(cx, 1, &val);
 628  * which compiles just fine, but runs the destructor well before the
 629  * intended time.
 630  *
 631  * They work by adding (#ifdef DEBUG) an additional parameter to the
 632  * guard object's constructor, with a default value, so that users of
 633  * the guard object's API do not need to do anything.  The default value
 634  * of this parameter is a temporary object.  C++ (ISO/IEC 14882:1998),
 635  * section 12.2 [class.temporary], clauses 4 and 5 seem to assume a
 636  * guarantee that temporaries are destroyed in the reverse of their
 637  * construction order, but I actually can't find a statement that that
 638  * is true in the general case (beyond the two specific cases mentioned
 639  * there).  However, it seems to be true.
 640  *
 641  * These classes are intended to be used only via the macros immediately
 642  * below them:
 643  *   JS_DECL_USE_GUARD_OBJECT_NOTIFIER declares (ifdef DEBUG) a member
 644  *     variable, and should be put where a declaration of a private
 645  *     member variable would be placed.
 646  *   JS_GUARD_OBJECT_NOTIFIER_PARAM should be placed at the end of the
 647  *     parameters to each constructor of the guard object; it declares
 648  *     (ifdef DEBUG) an additional parameter.
 649  *   JS_GUARD_OBJECT_NOTIFIER_INIT is a statement that belongs in each
 650  *     constructor.  It uses the parameter declared by
 651  *     JS_GUARD_OBJECT_NOTIFIER_PARAM.
 652  */
 653 #ifdef DEBUG
 654 class JS_FRIEND_API(JSGuardObjectNotifier)
 655 {
 656 private:
 657     bool* mStatementDone;
 658 public:
 659     JSGuardObjectNotifier() : mStatementDone(NULL) {}
 660
 661     ~JSGuardObjectNotifier() {
 662         *mStatementDone = true;
 663     }
 664
 665     void setStatementDone(bool *aStatementDone) {
 666         mStatementDone = aStatementDone;
 667     }
 668 };
 669
 670 class JS_FRIEND_API(JSGuardObjectNotificationReceiver)
 671 {
 672 private:
 673     bool mStatementDone;
 674 public:
 675     JSGuardObjectNotificationReceiver() : mStatementDone(false) {}
 676
 677     ~JSGuardObjectNotificationReceiver() {
 678         /*
 679          * Assert that the guard object was not used as a temporary.
 680          * (Note that this assert might also fire if Init is not called
 681          * because the guard object's implementation is not using the
 682          * above macros correctly.)
 683          */
 684         JS_ASSERT(mStatementDone);
 685     }
 686
 687     void Init(const JSGuardObjectNotifier &aNotifier) {
 688         /*
 689          * aNotifier is passed as a const reference so that we can pass a
 690          * temporary, but we really intend it as non-const
 691          */
 692         const_cast<JSGuardObjectNotifier&>(aNotifier).
 693             setStatementDone(&mStatementDone);
 694     }
 695 };
 696
 697 #define JS_DECL_USE_GUARD_OBJECT_NOTIFIER \
 698     JSGuardObjectNotificationReceiver _mCheckNotUsedAsTemporary;
 699 #define JS_GUARD_OBJECT_NOTIFIER_PARAM \
 700     , const JSGuardObjectNotifier& _notifier = JSGuardObjectNotifier()
 701 #define JS_GUARD_OBJECT_NOTIFIER_PARAM_NO_INIT \
 702     , const JSGuardObjectNotifier& _notifier
 703 #define JS_GUARD_OBJECT_NOTIFIER_PARAM0 \
 704     const JSGuardObjectNotifier& _notifier = JSGuardObjectNotifier()
 705 #define JS_GUARD_OBJECT_NOTIFIER_INIT \
 706     JS_BEGIN_MACRO _mCheckNotUsedAsTemporary.Init(_notifier); JS_END_MACRO
 707
 708 #else /* defined(DEBUG) */
 709
 710 #define JS_DECL_USE_GUARD_OBJECT_NOTIFIER
 711 #define JS_GUARD_OBJECT_NOTIFIER_PARAM
 712 #define JS_GUARD_OBJECT_NOTIFIER_PARAM_NO_INIT
 713 #define JS_GUARD_OBJECT_NOTIFIER_PARAM0
 714 #define JS_GUARD_OBJECT_NOTIFIER_INIT JS_BEGIN_MACRO JS_END_MACRO
 715
 716 #endif /* !defined(DEBUG) */
 717
 718 namespace js {
 719
 720 /*
 721  * "Move" References
 722  *
 723  * Some types can be copied much more efficiently if we know the original's
 724  * value need not be preserved --- that is, if we are doing a "move", not a
 725  * "copy". For example, if we have:
 726  *
 727  *   Vector<T> u;
 728  *   Vector<T> v(u);
 729  *
 730  * the constructor for v must apply a copy constructor to each element of u ---
 731  * taking time linear in the length of u. However, if we know we will not need u
 732  * any more once v has been initialized, then we could initialize v very
 733  * efficiently simply by stealing u's dynamically allocated buffer and giving it
 734  * to v --- a constant-time operation, regardless of the size of u.
 735  *
 736  * Moves often appear in container implementations. For example, when we append
 737  * to a vector, we may need to resize its buffer. This entails moving each of
 738  * its extant elements from the old, smaller buffer to the new, larger buffer.
 739  * But once the elements have been migrated, we're just going to throw away the
 740  * old buffer; we don't care if they still have their values. So if the vector's
 741  * element type can implement "move" more efficiently than "copy", the vector
 742  * resizing should by all means use a "move" operation. Hash tables also need to
 743  * be resized.
 744  *
 745  * The details of the optimization, and whether it's worth applying, vary from
 746  * one type to the next. And while some constructor calls are moves, many really
 747  * are copies, and can't be optimized this way. So we need:
 748  *
 749  * 1) a way for a particular invocation of a copy constructor to say that it's
 750  *    really a move, and that the value of the original isn't important
 751  *    afterwards (althought it must still be safe to destroy); and
 752  *
 753  * 2) a way for a type (like Vector) to announce that it can be moved more
 754  *    efficiently than it can be copied, and provide an implementation of that
 755  *    move operation.
 756  *
 757  * The Move(T &) function takes a reference to a T, and returns an MoveRef<T>
 758  * referring to the same value; that's 1). An MoveRef<T> is simply a reference
 759  * to a T, annotated to say that a copy constructor applied to it may move that
 760  * T, instead of copying it. Finally, a constructor that accepts an MoveRef<T>
 761  * should perform a more efficient move, instead of a copy, providing 2).
 762  *
 763  * So, where we might define a copy constructor for a class C like this:
 764  *
 765  *   C(const C &rhs) { ... copy rhs to this ... }
 766  *
 767  * we would declare a move constructor like this:
 768  *
 769  *   C(MoveRef<C> rhs) { ... move rhs to this ... }
 770  *
 771  * And where we might perform a copy like this:
 772  *
 773  *   C c2(c1);
 774  *
 775  * we would perform a move like this:
 776  *
 777  *   C c2(Move(c1))
 778  *
 779  * Note that MoveRef<T> implicitly converts to T &, so you can pass an
 780  * MoveRef<T> to an ordinary copy constructor for a type that doesn't support a
 781  * special move constructor, and you'll just get a copy. This means that
 782  * templates can use Move whenever they know they won't use the original value
 783  * any more, even if they're not sure whether the type at hand has a specialized
 784  * move constructor. If it doesn't, the MoveRef<T> will just convert to a T &,
 785  * and the ordinary copy constructor will apply.
 786  *
 787  * A class with a move constructor can also provide a move assignment operator,
 788  * which runs this's destructor, and then applies the move constructor to
 789  * *this's memory. A typical definition:
 790  *
 791  *   C &operator=(MoveRef<C> rhs) {
 792  *     this->~C();
 793  *     new(this) C(rhs);
 794  *     return *this;
 795  *   }
 796  *
 797  * With that in place, one can write move assignments like this:
 798  *
 799  *   c2 = Move(c1);
 800  *
 801  * This destroys c1, moves c1's value to c2, and leaves c1 in an undefined but
 802  * destructible state.
 803  *
 804  * This header file defines MoveRef and Move in the js namespace. It's up to
 805  * individual containers to annotate moves as such, by calling Move; and it's up
 806  * to individual types to define move constructors.
 807  *
 808  * One hint: if you're writing a move constructor where the type has members
 809  * that should be moved themselves, it's much nicer to write this:
 810  *
 811  *   C(MoveRef<C> c) : x(c->x), y(c->y) { }
 812  *
 813  * than the equivalent:
 814  *
 815  *   C(MoveRef<C> c) { new(&x) X(c->x); new(&y) Y(c->y); }
 816  *
 817  * especially since GNU C++ fails to notice that this does indeed initialize x
 818  * and y, which may matter if they're const.
 819  */
 820 template<typename T>
 821 class MoveRef {
 822   public:
 823     typedef T Referent;
 824     explicit MoveRef(T &t) : pointer(&t) { }
 825     T &operator*()  const { return *pointer; }
 826     T *operator->() const { return  pointer; }
 827 #ifdef __GXX_EXPERIMENTAL_CXX0X__
 828     /*
 829      * If MoveRef is used in a rvalue position (which is expected), we can
 830      * end up in a situation where, without this ifdef, we would try to pass
 831      * a T& to a move constructor, which fails. It is not clear if the compiler
 832      * should instead use the copy constructor, but for now this lets us build
 833      * with clang. See bug 689066 and llvm.org/pr11003 for the details.
 834      * Note: We can probably remove MoveRef completely once we are comfortable
 835      * using c++11.
 836      */
 837     operator T&& ()  const { return static_cast<T&&>(*pointer); }
 838 #else
 839     operator T& ()   const { return *pointer; }
 840 #endif
 841   private:
 842     T *pointer;
 843 };
 844
 845 template<typename T>
 846 MoveRef<T> Move(T &t) { return MoveRef<T>(t); }
 847
 848 template<typename T>
 849 MoveRef<T> Move(const T &t) { return MoveRef<T>(const_cast<T &>(t)); }
 850
 851 /* Useful for implementing containers that assert non-reentrancy */
 852 class ReentrancyGuard
 853 {
 854     /* ReentrancyGuard is not copyable. */
 855     ReentrancyGuard(const ReentrancyGuard &);
 856     void operator=(const ReentrancyGuard &);
 857
 858 #ifdef DEBUG
 859     bool &entered;
 860 #endif
 861   public:
 862     template <class T>
 863 #ifdef DEBUG
 864     ReentrancyGuard(T &obj)
 865       : entered(obj.entered)
 866 #else
 867     ReentrancyGuard(T &/*obj*/)
 868 #endif
 869     {
 870 #ifdef DEBUG
 871         JS_ASSERT(!entered);
 872         entered = true;
 873 #endif
 874     }
 875     ~ReentrancyGuard()
 876     {
 877 #ifdef DEBUG
 878         entered = false;
 879 #endif
 880     }
 881 };
 882
 883 /*
 884  * Round x up to the nearest power of 2.  This function assumes that the most
 885  * significant bit of x is not set, which would lead to overflow.
 886  */
 887 JS_ALWAYS_INLINE size_t
 888 RoundUpPow2(size_t x)
 889 {
 890     return size_t(1) << JS_CEILING_LOG2W(x);
 891 }
 892
 893 } /* namespace js */
 894
 895 #endif /* defined(__cplusplus) */
 896
 897 /*
 898  * This signature is for malloc_usable_size-like functions used to measure
 899  * memory usage.  A return value of zero indicates that the size is unknown,
 900  * and so a fall-back computation should be done for the size.
 901  */
 902 typedef size_t(*JSUsableSizeFun)(void *p);
 903
 904 /* sixgill annotation defines */
 905 #ifndef HAVE_STATIC_ANNOTATIONS
 906 # define HAVE_STATIC_ANNOTATIONS
 907 # ifdef XGILL_PLUGIN
 908 #  define STATIC_PRECONDITION(COND)         __attribute__((precondition(#COND)))
 909 #  define STATIC_PRECONDITION_ASSUME(COND)  __attribute__((precondition_assume(#COND)))
 910 #  define STATIC_POSTCONDITION(COND)        __attribute__((postcondition(#COND)))
 911 #  define STATIC_POSTCONDITION_ASSUME(COND) __attribute__((postcondition_assume(#COND)))
 912 #  define STATIC_INVARIANT(COND)            __attribute__((invariant(#COND)))
 913 #  define STATIC_INVARIANT_ASSUME(COND)     __attribute__((invariant_assume(#COND)))
 914 #  define STATIC_PASTE2(X,Y) X ## Y
 915 #  define STATIC_PASTE1(X,Y) STATIC_PASTE2(X,Y)
 916 #  define STATIC_ASSERT(COND)                        \
 917   JS_BEGIN_MACRO                                     \
 918     __attribute__((assert_static(#COND), unused))    \
 919     int STATIC_PASTE1(assert_static_, __COUNTER__);  \
 920   JS_END_MACRO
 921 #  define STATIC_ASSUME(COND)                        \
 922   JS_BEGIN_MACRO                                     \
 923     __attribute__((assume_static(#COND), unused))    \
 924     int STATIC_PASTE1(assume_static_, __COUNTER__);  \
 925   JS_END_MACRO
 926 #  define STATIC_ASSERT_RUNTIME(COND)                       \
 927   JS_BEGIN_MACRO                                            \
 928     __attribute__((assert_static_runtime(#COND), unused))   \
 929     int STATIC_PASTE1(assert_static_runtime_, __COUNTER__); \
 930   JS_END_MACRO
 931 # else /* XGILL_PLUGIN */
 932 #  define STATIC_PRECONDITION(COND)          /* nothing */
 933 #  define STATIC_PRECONDITION_ASSUME(COND)   /* nothing */
 934 #  define STATIC_POSTCONDITION(COND)         /* nothing */
 935 #  define STATIC_POSTCONDITION_ASSUME(COND)  /* nothing */
 936 #  define STATIC_INVARIANT(COND)             /* nothing */
 937 #  define STATIC_INVARIANT_ASSUME(COND)      /* nothing */
 938 #  define STATIC_ASSERT(COND)          JS_BEGIN_MACRO /* nothing */ JS_END_MACRO
 939 #  define STATIC_ASSUME(COND)          JS_BEGIN_MACRO /* nothing */ JS_END_MACRO
 940 #  define STATIC_ASSERT_RUNTIME(COND)  JS_BEGIN_MACRO /* nothing */ JS_END_MACRO
 941 # endif /* XGILL_PLUGIN */
 942 # define STATIC_SKIP_INFERENCE STATIC_INVARIANT(skip_inference())
 943 #endif /* HAVE_STATIC_ANNOTATIONS */
 944
 945 #endif /* js_utility_h__ */