js/src/jsutil.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla Communicator client code, released
  17  * March 31, 1998.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1998
  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 of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or 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 /*
  41  * PR assertion checker.
  42  */
  43
  44 #ifndef jsutil_h___
  45 #define jsutil_h___
  46
  47 #include "jstypes.h"
  48 #include <stdlib.h>
  49
  50 JS_BEGIN_EXTERN_C
  51
  52 /*
  53  * JS_Assert is present even in release builds, for the benefit of applications
  54  * that build DEBUG and link against a non-DEBUG SpiderMonkey library.
  55  */
  56 extern JS_PUBLIC_API(void)
  57 JS_Assert(const char *s, const char *file, JSIntn ln);
  58
  59 #define JS_CRASH_UNLESS(__cond)                                                 \
  60     JS_BEGIN_MACRO                                                              \
  61         if (!(__cond)) {                                                        \
  62             *(int *)(uintptr_t)0xccadbeef = 0;                                  \
  63             ((void(*)())0)(); /* More reliable, but doesn't say CCADBEEF */     \
  64         }                                                                       \
  65     JS_END_MACRO
  66
  67 #ifdef DEBUG
  68
  69 #define JS_ASSERT(expr)                                                       \
  70     ((expr) ? (void)0 : JS_Assert(#expr, __FILE__, __LINE__))
  71
  72 #define JS_ASSERT_IF(cond, expr)                                              \
  73     ((!(cond) || (expr)) ? (void)0 : JS_Assert(#expr, __FILE__, __LINE__))
  74
  75 #define JS_NOT_REACHED(reason)                                                \
  76     JS_Assert(reason, __FILE__, __LINE__)
  77
  78 #define JS_ALWAYS_TRUE(expr) JS_ASSERT(expr)
  79
  80 # ifdef JS_THREADSAFE
  81 # define JS_THREADSAFE_ASSERT(expr) JS_ASSERT(expr)
  82 # else
  83 # define JS_THREADSAFE_ASSERT(expr) ((void) 0)
  84 # endif
  85
  86 #else
  87
  88 #define JS_ASSERT(expr)         ((void) 0)
  89 #define JS_ASSERT_IF(cond,expr) ((void) 0)
  90 #define JS_NOT_REACHED(reason)
  91 #define JS_ALWAYS_TRUE(expr)    ((void) (expr))
  92 #define JS_THREADSAFE_ASSERT(expr) ((void) 0)
  93
  94 #endif /* defined(DEBUG) */
  95
  96 /*
  97  * Compile-time assert. "cond" must be a constant expression.
  98  * The macro can be used only in places where an "extern" declaration is
  99  * allowed.
 100  */
 101
 102 #ifdef __SUNPRO_CC
 103 /*
 104  * Sun Studio C++ compiler has a bug
 105  * "sizeof expression not accepted as size of array parameter"
 106  * It happens when js_static_assert() function is declared inside functions.
 107  * The bug number is 6688515. It is not public yet.
 108  * Therefore, for Sun Studio, declare js_static_assert as an array instead.
 109  */
 110 #define JS_STATIC_ASSERT(cond) extern char js_static_assert[(cond) ? 1 : -1]
 111 #else
 112 #ifdef __COUNTER__
 113     #define JS_STATIC_ASSERT_GLUE1(x,y) x##y
 114     #define JS_STATIC_ASSERT_GLUE(x,y) JS_STATIC_ASSERT_GLUE1(x,y)
 115     #define JS_STATIC_ASSERT(cond)                                            \
 116         typedef int JS_STATIC_ASSERT_GLUE(js_static_assert, __COUNTER__)[(cond) ? 1 : -1]
 117 #else
 118     #define JS_STATIC_ASSERT(cond) extern void js_static_assert(int arg[(cond) ? 1 : -1])
 119 #endif
 120 #endif
 121
 122 #define JS_STATIC_ASSERT_IF(cond, expr) JS_STATIC_ASSERT(!(cond) || (expr))
 123
 124 /*
 125  * Abort the process in a non-graceful manner. This will cause a core file,
 126  * call to the debugger or other moral equivalent as well as causing the
 127  * entire process to stop.
 128  */
 129 extern JS_PUBLIC_API(void) JS_Abort(void);
 130
 131 #ifdef DEBUG
 132 # define JS_BASIC_STATS 1
 133 #endif
 134
 135 #ifdef DEBUG_brendan
 136 # define JS_SCOPE_DEPTH_METER 1
 137 #endif
 138
 139 #ifdef JS_BASIC_STATS
 140
 141 #include <stdio.h>
 142
 143 typedef struct JSBasicStats {
 144     uint32      num;
 145     uint32      max;
 146     double      sum;
 147     double      sqsum;
 148     uint32      logscale;           /* logarithmic scale: 0 (linear), 2, 10 */
 149     uint32      hist[11];
 150 } JSBasicStats;
 151
 152 #define JS_INIT_STATIC_BASIC_STATS  {0,0,0,0,0,{0,0,0,0,0,0,0,0,0,0,0}}
 153 #define JS_BASIC_STATS_INIT(bs)     memset((bs), 0, sizeof(JSBasicStats))
 154
 155 #define JS_BASIC_STATS_ACCUM(bs,val)                                          \
 156     JS_BasicStatsAccum(bs, val)
 157
 158 #define JS_MeanAndStdDevBS(bs,sigma)                                          \
 159     JS_MeanAndStdDev((bs)->num, (bs)->sum, (bs)->sqsum, sigma)
 160
 161 extern void
 162 JS_BasicStatsAccum(JSBasicStats *bs, uint32 val);
 163
 164 extern double
 165 JS_MeanAndStdDev(uint32 num, double sum, double sqsum, double *sigma);
 166
 167 extern void
 168 JS_DumpBasicStats(JSBasicStats *bs, const char *title, FILE *fp);
 169
 170 extern void
 171 JS_DumpHistogram(JSBasicStats *bs, FILE *fp);
 172
 173 #else
 174
 175 #define JS_BASIC_STATS_ACCUM(bs,val) /* nothing */
 176
 177 #endif /* JS_BASIC_STATS */
 178
 179
 180 #if defined(DEBUG_notme) && defined(XP_UNIX)
 181
 182 typedef struct JSCallsite JSCallsite;
 183
 184 struct JSCallsite {
 185     uint32      pc;
 186     char        *name;
 187     const char  *library;
 188     int         offset;
 189     JSCallsite  *parent;
 190     JSCallsite  *siblings;
 191     JSCallsite  *kids;
 192     void        *handy;
 193 };
 194
 195 extern JS_FRIEND_API(JSCallsite *)
 196 JS_Backtrace(int skip);
 197
 198 extern JS_FRIEND_API(void)
 199 JS_DumpBacktrace(JSCallsite *trace);
 200 #endif
 201
 202 #if defined JS_USE_CUSTOM_ALLOCATOR
 203
 204 #include "jscustomallocator.h"
 205
 206 #else
 207
 208 static JS_INLINE void* js_malloc(size_t bytes) {
 209     return malloc(bytes);
 210 }
 211
 212 static JS_INLINE void* js_calloc(size_t bytes) {
 213     return calloc(bytes, 1);
 214 }
 215
 216 static JS_INLINE void* js_realloc(void* p, size_t bytes) {
 217     return realloc(p, bytes);
 218 }
 219
 220 static JS_INLINE void js_free(void* p) {
 221     free(p);
 222 }
 223 #endif/* JS_USE_CUSTOM_ALLOCATOR */
 224
 225 JS_END_EXTERN_C
 226
 227 #ifdef __cplusplus
 228
 229 /**
 230  * The following classes are designed to cause assertions to detect
 231  * inadvertent use of guard objects as temporaries.  In other words,
 232  * when we have a guard object whose only purpose is its constructor and
 233  * destructor (and is never otherwise referenced), the intended use
 234  * might be:
 235  *     JSAutoTempValueRooter tvr(cx, 1, &val);
 236  * but is is easy to accidentally write:
 237  *     JSAutoTempValueRooter(cx, 1, &val);
 238  * which compiles just fine, but runs the destructor well before the
 239  * intended time.
 240  *
 241  * They work by adding (#ifdef DEBUG) an additional parameter to the
 242  * guard object's constructor, with a default value, so that users of
 243  * the guard object's API do not need to do anything.  The default value
 244  * of this parameter is a temporary object.  C++ (ISO/IEC 14882:1998),
 245  * section 12.2 [class.temporary], clauses 4 and 5 seem to assume a
 246  * guarantee that temporaries are destroyed in the reverse of their
 247  * construction order, but I actually can't find a statement that that
 248  * is true in the general case (beyond the two specific cases mentioned
 249  * there).  However, it seems to be true.
 250  *
 251  * These classes are intended to be used only via the macros immediately
 252  * below them:
 253  *   JS_DECL_USE_GUARD_OBJECT_NOTIFIER declares (ifdef DEBUG) a member
 254  *     variable, and should be put where a declaration of a private
 255  *     member variable would be placed.
 256  *   JS_GUARD_OBJECT_NOTIFIER_PARAM should be placed at the end of the
 257  *     parameters to each constructor of the guard object; it declares
 258  *     (ifdef DEBUG) an additional parameter.
 259  *   JS_GUARD_OBJECT_NOTIFIER_INIT is a statement that belongs in each
 260  *     constructor.  It uses the parameter declared by
 261  *     JS_GUARD_OBJECT_NOTIFIER_PARAM.
 262  */
 263 #ifdef DEBUG
 264 class JSGuardObjectNotifier
 265 {
 266 private:
 267     bool* mStatementDone;
 268 public:
 269     JSGuardObjectNotifier() : mStatementDone(NULL) {}
 270
 271     ~JSGuardObjectNotifier() {
 272         *mStatementDone = true;
 273     }
 274
 275     void setStatementDone(bool *aStatementDone) {
 276         mStatementDone = aStatementDone;
 277     }
 278 };
 279
 280 class JSGuardObjectNotificationReceiver
 281 {
 282 private:
 283     bool mStatementDone;
 284 public:
 285     JSGuardObjectNotificationReceiver() : mStatementDone(false) {}
 286
 287     ~JSGuardObjectNotificationReceiver() {
 288         /*
 289          * Assert that the guard object was not used as a temporary.
 290          * (Note that this assert might also fire if Init is not called
 291          * because the guard object's implementation is not using the
 292          * above macros correctly.)
 293          */
 294         JS_ASSERT(mStatementDone);
 295     }
 296
 297     void Init(const JSGuardObjectNotifier &aNotifier) {
 298         /*
 299          * aNotifier is passed as a const reference so that we can pass a
 300          * temporary, but we really intend it as non-const
 301          */
 302         const_cast<JSGuardObjectNotifier&>(aNotifier).
 303             setStatementDone(&mStatementDone);
 304     }
 305 };
 306
 307 #define JS_DECL_USE_GUARD_OBJECT_NOTIFIER \
 308     JSGuardObjectNotificationReceiver _mCheckNotUsedAsTemporary;
 309 #define JS_GUARD_OBJECT_NOTIFIER_PARAM \
 310     , const JSGuardObjectNotifier& _notifier = JSGuardObjectNotifier()
 311 #define JS_GUARD_OBJECT_NOTIFIER_INIT \
 312     JS_BEGIN_MACRO _mCheckNotUsedAsTemporary.Init(_notifier); JS_END_MACRO
 313
 314 #else /* defined(DEBUG) */
 315
 316 #define JS_DECL_USE_GUARD_OBJECT_NOTIFIER
 317 #define JS_GUARD_OBJECT_NOTIFIER_PARAM
 318 #define JS_GUARD_OBJECT_NOTIFIER_INIT JS_BEGIN_MACRO JS_END_MACRO
 319
 320 #endif /* !defined(DEBUG) */
 321
 322 namespace js {
 323
 324 template <class T>
 325 JS_ALWAYS_INLINE static void
 326 PodZero(T *t)
 327 {
 328     memset(t, 0, sizeof(T));
 329 }
 330
 331 template <class T>
 332 JS_ALWAYS_INLINE static void
 333 PodZero(T *t, size_t nelem)
 334 {
 335     memset(t, 0, nelem * sizeof(T));
 336 }
 337
 338 /*
 339  * Arrays implicitly convert to pointers to their first element, which is
 340  * dangerous when combined with the above PodZero definitions. Adding an
 341  * overload for arrays is ambiguous, so we need another identifier. The
 342  * ambiguous overload is left to catch mistaken uses of PodZero; if you get a
 343  * compile error involving PodZero and array types, use PodArrayZero instead.
 344  */
 345 template <class T, size_t N> static void PodZero(T (&)[N]);          /* undefined */
 346 template <class T, size_t N> static void PodZero(T (&)[N], size_t);  /* undefined */
 347
 348 template <class T, size_t N>
 349 JS_ALWAYS_INLINE static void
 350 PodArrayZero(T (&t)[N])
 351 {
 352     memset(t, 0, N * sizeof(T));
 353 }
 354
 355 } /* namespace js */
 356
 357 #endif /* defined(__cplusplus) */
 358
 359 #endif /* jsutil_h___ */