js/src/jsdbgapi.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=8 sw=4 et tw=99:
   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  *   Nick Fitzgerald <nfitzgerald@mozilla.com>
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of
  29  * either of the GNU General Public License Version 2 or later (the "GPL"),
  30  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  31  * in which case the provisions of the GPL or the LGPL are applicable instead
  32  * of those above. If you wish to allow use of your version of this file only
  33  * under the terms of either the GPL or the LGPL, and not to allow others to
  34  * use your version of this file under the terms of the MPL, indicate your
  35  * decision by deleting the provisions above and replace them with the notice
  36  * and other provisions required by the GPL or the LGPL. If you do not delete
  37  * the provisions above, a recipient may use your version of this file under
  38  * the terms of any one of the MPL, the GPL or the LGPL.
  39  *
  40  * ***** END LICENSE BLOCK ***** */
  41
  42 #ifndef jsdbgapi_h___
  43 #define jsdbgapi_h___
  44 /*
  45  * JS debugger API.
  46  */
  47 #include "jsapi.h"
  48 #include "jsprvtd.h"
  49
  50 JS_BEGIN_EXTERN_C
  51
  52 extern JS_PUBLIC_API(JSCrossCompartmentCall *)
  53 JS_EnterCrossCompartmentCallScript(JSContext *cx, JSScript *target);
  54
  55 extern JS_PUBLIC_API(JSCrossCompartmentCall *)
  56 JS_EnterCrossCompartmentCallStackFrame(JSContext *cx, JSStackFrame *target);
  57
  58 #ifdef __cplusplus
  59 JS_END_EXTERN_C
  60
  61 namespace JS {
  62
  63 class JS_PUBLIC_API(AutoEnterScriptCompartment)
  64 {
  65   protected:
  66     JSCrossCompartmentCall *call;
  67
  68   public:
  69     AutoEnterScriptCompartment() : call(NULL) {}
  70
  71     bool enter(JSContext *cx, JSScript *target);
  72
  73     bool entered() const { return call != NULL; }
  74
  75     ~AutoEnterScriptCompartment() {
  76         if (call && call != reinterpret_cast<JSCrossCompartmentCall*>(1))
  77             JS_LeaveCrossCompartmentCall(call);
  78     }
  79 };
  80
  81 class JS_PUBLIC_API(AutoEnterFrameCompartment) : public AutoEnterScriptCompartment
  82 {
  83   public:
  84     bool enter(JSContext *cx, JSStackFrame *target);
  85 };
  86
  87 } /* namespace JS */
  88
  89 #ifdef DEBUG
  90 JS_FRIEND_API(void) js_DumpValue(const js::Value &val);
  91 JS_FRIEND_API(void) js_DumpId(jsid id);
  92 JS_FRIEND_API(void) js_DumpStackFrame(JSContext *cx, js::StackFrame *start = NULL);
  93 #endif
  94 JS_FRIEND_API(void) js_DumpBacktrace(JSContext *cx);
  95
  96 JS_BEGIN_EXTERN_C
  97 #endif
  98
  99 extern JS_PUBLIC_API(JSString *)
 100 JS_DecompileScript(JSContext *cx, JSScript *script, const char *name, unsigned indent);
 101
 102 /*
 103  * Currently, we only support runtime-wide debugging. In the future, we should
 104  * be able to support compartment-wide debugging.
 105  */
 106 extern JS_PUBLIC_API(void)
 107 JS_SetRuntimeDebugMode(JSRuntime *rt, JSBool debug);
 108
 109 /*
 110  * Debug mode is a compartment-wide mode that enables a debugger to attach
 111  * to and interact with running methodjit-ed frames. In particular, it causes
 112  * every function to be compiled as if an eval was present (so eval-in-frame)
 113  * can work, and it ensures that functions can be re-JITed for other debug
 114  * features. In general, it is not safe to interact with frames that were live
 115  * before debug mode was enabled. For this reason, it is also not safe to
 116  * enable debug mode while frames are live.
 117  */
 118
 119 /* Get current state of debugging mode. */
 120 extern JS_PUBLIC_API(JSBool)
 121 JS_GetDebugMode(JSContext *cx);
 122
 123 /*
 124  * Turn on/off debugging mode for a single compartment. This should only be
 125  * used when no code from this compartment is running or on the stack in any
 126  * thread.
 127  */
 128 JS_FRIEND_API(JSBool)
 129 JS_SetDebugModeForCompartment(JSContext *cx, JSCompartment *comp, JSBool debug);
 130
 131 /*
 132  * Turn on/off debugging mode for a context's compartment.
 133  */
 134 JS_FRIEND_API(JSBool)
 135 JS_SetDebugMode(JSContext *cx, JSBool debug);
 136
 137 /* Turn on single step mode. */
 138 extern JS_PUBLIC_API(JSBool)
 139 JS_SetSingleStepMode(JSContext *cx, JSScript *script, JSBool singleStep);
 140
 141 /* The closure argument will be marked. */
 142 extern JS_PUBLIC_API(JSBool)
 143 JS_SetTrap(JSContext *cx, JSScript *script, jsbytecode *pc,
 144            JSTrapHandler handler, jsval closure);
 145
 146 extern JS_PUBLIC_API(void)
 147 JS_ClearTrap(JSContext *cx, JSScript *script, jsbytecode *pc,
 148              JSTrapHandler *handlerp, jsval *closurep);
 149
 150 extern JS_PUBLIC_API(void)
 151 JS_ClearScriptTraps(JSContext *cx, JSScript *script);
 152
 153 extern JS_PUBLIC_API(void)
 154 JS_ClearAllTrapsForCompartment(JSContext *cx);
 155
 156 extern JS_PUBLIC_API(JSBool)
 157 JS_SetInterrupt(JSRuntime *rt, JSInterruptHook handler, void *closure);
 158
 159 extern JS_PUBLIC_API(JSBool)
 160 JS_ClearInterrupt(JSRuntime *rt, JSInterruptHook *handlerp, void **closurep);
 161
 162 /************************************************************************/
 163
 164 extern JS_PUBLIC_API(JSBool)
 165 JS_SetWatchPoint(JSContext *cx, JSObject *obj, jsid id,
 166                  JSWatchPointHandler handler, JSObject *closure);
 167
 168 extern JS_PUBLIC_API(JSBool)
 169 JS_ClearWatchPoint(JSContext *cx, JSObject *obj, jsid id,
 170                    JSWatchPointHandler *handlerp, JSObject **closurep);
 171
 172 extern JS_PUBLIC_API(JSBool)
 173 JS_ClearWatchPointsForObject(JSContext *cx, JSObject *obj);
 174
 175 extern JS_PUBLIC_API(JSBool)
 176 JS_ClearAllWatchPoints(JSContext *cx);
 177
 178 /************************************************************************/
 179
 180 extern JS_PUBLIC_API(unsigned)
 181 JS_PCToLineNumber(JSContext *cx, JSScript *script, jsbytecode *pc);
 182
 183 extern JS_PUBLIC_API(jsbytecode *)
 184 JS_LineNumberToPC(JSContext *cx, JSScript *script, unsigned lineno);
 185
 186 extern JS_PUBLIC_API(jsbytecode *)
 187 JS_EndPC(JSContext *cx, JSScript *script);
 188
 189 extern JS_PUBLIC_API(JSBool)
 190 JS_GetLinePCs(JSContext *cx, JSScript *script,
 191               unsigned startLine, unsigned maxLines,
 192               unsigned* count, unsigned** lines, jsbytecode*** pcs);
 193
 194 extern JS_PUBLIC_API(unsigned)
 195 JS_GetFunctionArgumentCount(JSContext *cx, JSFunction *fun);
 196
 197 extern JS_PUBLIC_API(JSBool)
 198 JS_FunctionHasLocalNames(JSContext *cx, JSFunction *fun);
 199
 200 /*
 201  * N.B. The mark is in the context temp pool and thus the caller must take care
 202  * to call JS_ReleaseFunctionLocalNameArray in a LIFO manner (wrt to any other
 203  * call that may use the temp pool.
 204  */
 205 extern JS_PUBLIC_API(uintptr_t *)
 206 JS_GetFunctionLocalNameArray(JSContext *cx, JSFunction *fun, void **markp);
 207
 208 extern JS_PUBLIC_API(JSAtom *)
 209 JS_LocalNameToAtom(uintptr_t w);
 210
 211 extern JS_PUBLIC_API(JSString *)
 212 JS_AtomKey(JSAtom *atom);
 213
 214 extern JS_PUBLIC_API(void)
 215 JS_ReleaseFunctionLocalNameArray(JSContext *cx, void *mark);
 216
 217 extern JS_PUBLIC_API(JSScript *)
 218 JS_GetFunctionScript(JSContext *cx, JSFunction *fun);
 219
 220 extern JS_PUBLIC_API(JSNative)
 221 JS_GetFunctionNative(JSContext *cx, JSFunction *fun);
 222
 223 extern JS_PUBLIC_API(JSPrincipals *)
 224 JS_GetScriptPrincipals(JSScript *script);
 225
 226 extern JS_PUBLIC_API(JSPrincipals *)
 227 JS_GetScriptOriginPrincipals(JSScript *script);
 228
 229 /*
 230  * Stack Frame Iterator
 231  *
 232  * Used to iterate through the JS stack frames to extract
 233  * information from the frames.
 234  */
 235
 236 extern JS_PUBLIC_API(JSStackFrame *)
 237 JS_FrameIterator(JSContext *cx, JSStackFrame **iteratorp);
 238
 239 extern JS_PUBLIC_API(JSScript *)
 240 JS_GetFrameScript(JSContext *cx, JSStackFrame *fp);
 241
 242 extern JS_PUBLIC_API(jsbytecode *)
 243 JS_GetFramePC(JSContext *cx, JSStackFrame *fp);
 244
 245 extern JS_PUBLIC_API(void *)
 246 JS_GetFrameAnnotation(JSContext *cx, JSStackFrame *fp);
 247
 248 extern JS_PUBLIC_API(void)
 249 JS_SetFrameAnnotation(JSContext *cx, JSStackFrame *fp, void *annotation);
 250
 251 extern JS_PUBLIC_API(JSBool)
 252 JS_IsScriptFrame(JSContext *cx, JSStackFrame *fp);
 253
 254 extern JS_PUBLIC_API(JSObject *)
 255 JS_GetFrameScopeChain(JSContext *cx, JSStackFrame *fp);
 256
 257 extern JS_PUBLIC_API(JSObject *)
 258 JS_GetFrameCallObject(JSContext *cx, JSStackFrame *fp);
 259
 260 extern JS_PUBLIC_API(JSBool)
 261 JS_GetFrameThis(JSContext *cx, JSStackFrame *fp, jsval *thisv);
 262
 263 extern JS_PUBLIC_API(JSFunction *)
 264 JS_GetFrameFunction(JSContext *cx, JSStackFrame *fp);
 265
 266 extern JS_PUBLIC_API(JSObject *)
 267 JS_GetFrameFunctionObject(JSContext *cx, JSStackFrame *fp);
 268
 269 JS_PUBLIC_API(JSFunction *)
 270 JS_GetScriptFunction(JSContext *cx, JSScript *script);
 271
 272 extern JS_PUBLIC_API(JSObject *)
 273 JS_GetParentOrScopeChain(JSContext *cx, JSObject *obj);
 274
 275 /* XXXrginda Initially published with typo */
 276 #define JS_IsContructorFrame JS_IsConstructorFrame
 277 extern JS_PUBLIC_API(JSBool)
 278 JS_IsConstructorFrame(JSContext *cx, JSStackFrame *fp);
 279
 280 extern JS_PUBLIC_API(JSBool)
 281 JS_IsDebuggerFrame(JSContext *cx, JSStackFrame *fp);
 282
 283 extern JS_PUBLIC_API(JSBool)
 284 JS_IsGlobalFrame(JSContext *cx, JSStackFrame *fp);
 285
 286 extern JS_PUBLIC_API(jsval)
 287 JS_GetFrameReturnValue(JSContext *cx, JSStackFrame *fp);
 288
 289 extern JS_PUBLIC_API(void)
 290 JS_SetFrameReturnValue(JSContext *cx, JSStackFrame *fp, jsval rval);
 291
 292 /**
 293  * Return fp's callee function object (fp->callee) if it has one. Note that
 294  * this API cannot fail. A null return means "no callee": fp is a global or
 295  * eval-from-global frame, not a call frame.
 296  */
 297 extern JS_PUBLIC_API(JSObject *)
 298 JS_GetFrameCalleeObject(JSContext *cx, JSStackFrame *fp);
 299
 300 /************************************************************************/
 301
 302 extern JS_PUBLIC_API(const char *)
 303 JS_GetScriptFilename(JSContext *cx, JSScript *script);
 304
 305 extern JS_PUBLIC_API(const jschar *)
 306 JS_GetScriptSourceMap(JSContext *cx, JSScript *script);
 307
 308 extern JS_PUBLIC_API(unsigned)
 309 JS_GetScriptBaseLineNumber(JSContext *cx, JSScript *script);
 310
 311 extern JS_PUBLIC_API(unsigned)
 312 JS_GetScriptLineExtent(JSContext *cx, JSScript *script);
 313
 314 extern JS_PUBLIC_API(JSVersion)
 315 JS_GetScriptVersion(JSContext *cx, JSScript *script);
 316
 317 /************************************************************************/
 318
 319 /*
 320  * Hook setters for script creation and destruction, see jsprvtd.h for the
 321  * typedefs.  These macros provide binary compatibility and newer, shorter
 322  * synonyms.
 323  */
 324 #define JS_SetNewScriptHook     JS_SetNewScriptHookProc
 325 #define JS_SetDestroyScriptHook JS_SetDestroyScriptHookProc
 326
 327 extern JS_PUBLIC_API(void)
 328 JS_SetNewScriptHook(JSRuntime *rt, JSNewScriptHook hook, void *callerdata);
 329
 330 extern JS_PUBLIC_API(void)
 331 JS_SetDestroyScriptHook(JSRuntime *rt, JSDestroyScriptHook hook,
 332                         void *callerdata);
 333
 334 /************************************************************************/
 335
 336 extern JS_PUBLIC_API(JSBool)
 337 JS_EvaluateUCInStackFrame(JSContext *cx, JSStackFrame *fp,
 338                           const jschar *chars, unsigned length,
 339                           const char *filename, unsigned lineno,
 340                           jsval *rval);
 341
 342 extern JS_PUBLIC_API(JSBool)
 343 JS_EvaluateInStackFrame(JSContext *cx, JSStackFrame *fp,
 344                         const char *bytes, unsigned length,
 345                         const char *filename, unsigned lineno,
 346                         jsval *rval);
 347
 348 /************************************************************************/
 349
 350 typedef struct JSPropertyDesc {
 351     jsval           id;         /* primary id, atomized string, or int */
 352     jsval           value;      /* property value */
 353     uint8_t         flags;      /* flags, see below */
 354     uint8_t         spare;      /* unused */
 355     uint16_t        slot;       /* argument/variable slot */
 356     jsval           alias;      /* alias id if JSPD_ALIAS flag */
 357 } JSPropertyDesc;
 358
 359 #define JSPD_ENUMERATE  0x01    /* visible to for/in loop */
 360 #define JSPD_READONLY   0x02    /* assignment is error */
 361 #define JSPD_PERMANENT  0x04    /* property cannot be deleted */
 362 #define JSPD_ALIAS      0x08    /* property has an alias id */
 363 #define JSPD_ARGUMENT   0x10    /* argument to function */
 364 #define JSPD_VARIABLE   0x20    /* local variable in function */
 365 #define JSPD_EXCEPTION  0x40    /* exception occurred fetching the property, */
 366                                 /* value is exception */
 367 #define JSPD_ERROR      0x80    /* native getter returned JS_FALSE without */
 368                                 /* throwing an exception */
 369
 370 typedef struct JSPropertyDescArray {
 371     uint32_t        length;     /* number of elements in array */
 372     JSPropertyDesc  *array;     /* alloc'd by Get, freed by Put */
 373 } JSPropertyDescArray;
 374
 375 typedef struct JSScopeProperty JSScopeProperty;
 376
 377 extern JS_PUBLIC_API(JSBool)
 378 JS_GetPropertyDescArray(JSContext *cx, JSObject *obj, JSPropertyDescArray *pda);
 379
 380 extern JS_PUBLIC_API(void)
 381 JS_PutPropertyDescArray(JSContext *cx, JSPropertyDescArray *pda);
 382
 383 /************************************************************************/
 384
 385 extern JS_PUBLIC_API(JSBool)
 386 JS_SetDebuggerHandler(JSRuntime *rt, JSDebuggerHandler hook, void *closure);
 387
 388 extern JS_PUBLIC_API(JSBool)
 389 JS_SetSourceHandler(JSRuntime *rt, JSSourceHandler handler, void *closure);
 390
 391 extern JS_PUBLIC_API(JSBool)
 392 JS_SetExecuteHook(JSRuntime *rt, JSInterpreterHook hook, void *closure);
 393
 394 extern JS_PUBLIC_API(JSBool)
 395 JS_SetCallHook(JSRuntime *rt, JSInterpreterHook hook, void *closure);
 396
 397 extern JS_PUBLIC_API(JSBool)
 398 JS_SetThrowHook(JSRuntime *rt, JSThrowHook hook, void *closure);
 399
 400 extern JS_PUBLIC_API(JSBool)
 401 JS_SetDebugErrorHook(JSRuntime *rt, JSDebugErrorHook hook, void *closure);
 402
 403 /************************************************************************/
 404
 405 extern JS_PUBLIC_API(size_t)
 406 JS_GetObjectTotalSize(JSContext *cx, JSObject *obj);
 407
 408 extern JS_PUBLIC_API(size_t)
 409 JS_GetFunctionTotalSize(JSContext *cx, JSFunction *fun);
 410
 411 extern JS_PUBLIC_API(size_t)
 412 JS_GetScriptTotalSize(JSContext *cx, JSScript *script);
 413
 414 /*
 415  * Return true if obj is a "system" object, that is, one created by
 416  * JS_NewSystemObject with the system flag set and not JS_NewObject.
 417  *
 418  * What "system" means is up to the API client.
 419  */
 420 extern JS_PUBLIC_API(JSBool)
 421 JS_IsSystemObject(JSContext *cx, JSObject *obj);
 422
 423 /*
 424  * Mark an object as being a system object. This should be called immediately
 425  * after allocating the object. A system object is an object for which
 426  * JS_IsSystemObject returns true.
 427  */
 428 extern JS_PUBLIC_API(JSBool)
 429 JS_MakeSystemObject(JSContext *cx, JSObject *obj);
 430
 431 /************************************************************************/
 432
 433 extern JS_FRIEND_API(void)
 434 js_RevertVersion(JSContext *cx);
 435
 436 extern JS_PUBLIC_API(const JSDebugHooks *)
 437 JS_GetGlobalDebugHooks(JSRuntime *rt);
 438
 439 /**
 440  * Start any profilers that are available and have been configured on for this
 441  * platform. This is NOT thread safe.
 442  *
 443  * The profileName is used by some profilers to describe the current profiling
 444  * run. It may be used for part of the filename of the output, but the
 445  * specifics depend on the profiler. Many profilers will ignore it. Passing in
 446  * NULL is legal; some profilers may use it to output to stdout or similar.
 447  *
 448  * Returns true if no profilers fail to start.
 449  */
 450 extern JS_PUBLIC_API(JSBool)
 451 JS_StartProfiling(const char *profileName);
 452
 453 /**
 454  * Stop any profilers that were previously started with JS_StartProfiling.
 455  * Returns true if no profilers fail to stop.
 456  */
 457 extern JS_PUBLIC_API(JSBool)
 458 JS_StopProfiling(const char *profileName);
 459
 460 /**
 461  * Write the current profile data to the given file, if applicable to whatever
 462  * profiler is being used.
 463  */
 464 extern JS_PUBLIC_API(JSBool)
 465 JS_DumpProfile(const char *outfile, const char *profileName);
 466
 467 /**
 468  * Pause currently active profilers (only supported by some profilers). Returns
 469  * whether any profilers failed to pause. (Profilers that do not support
 470  * pause/resume do not count.)
 471  */
 472 extern JS_PUBLIC_API(JSBool)
 473 JS_PauseProfilers(const char *profileName);
 474
 475 /**
 476  * Resume suspended profilers
 477  */
 478 extern JS_PUBLIC_API(JSBool)
 479 JS_ResumeProfilers(const char *profileName);
 480
 481 /**
 482  * Add various profiling-related functions as properties of the given object.
 483  */
 484 extern JS_PUBLIC_API(JSBool)
 485 JS_DefineProfilingFunctions(JSContext *cx, JSObject *obj);
 486
 487 /* Defined in vm/Debugger.cpp. */
 488 extern JS_PUBLIC_API(JSBool)
 489 JS_DefineDebuggerObject(JSContext *cx, JSObject *obj);
 490
 491 /**
 492  * The profiling API calls are not able to report errors, so they use a
 493  * thread-unsafe global memory buffer to hold the last error encountered. This
 494  * should only be called after something returns false.
 495  */
 496 JS_PUBLIC_API(const char *)
 497 JS_UnsafeGetLastProfilingError();
 498
 499 #ifdef MOZ_CALLGRIND
 500
 501 extern JS_FRIEND_API(JSBool)
 502 js_StopCallgrind();
 503
 504 extern JS_FRIEND_API(JSBool)
 505 js_StartCallgrind();
 506
 507 extern JS_FRIEND_API(JSBool)
 508 js_DumpCallgrind(const char *outfile);
 509
 510 #endif /* MOZ_CALLGRIND */
 511
 512 #ifdef MOZ_VTUNE
 513
 514 extern JS_FRIEND_API(bool)
 515 js_StartVtune(const char *profileName);
 516
 517 extern JS_FRIEND_API(bool)
 518 js_StopVtune();
 519
 520 extern JS_FRIEND_API(bool)
 521 js_PauseVtune();
 522
 523 extern JS_FRIEND_API(bool)
 524 js_ResumeVtune();
 525
 526 #endif /* MOZ_VTUNE */
 527
 528 #ifdef __linux__
 529
 530 extern JS_FRIEND_API(JSBool)
 531 js_StartPerf();
 532
 533 extern JS_FRIEND_API(JSBool)
 534 js_StopPerf();
 535
 536 #endif /* __linux__ */
 537
 538 extern JS_PUBLIC_API(void)
 539 JS_DumpBytecode(JSContext *cx, JSScript *script);
 540
 541 extern JS_PUBLIC_API(void)
 542 JS_DumpCompartmentBytecode(JSContext *cx);
 543
 544 extern JS_PUBLIC_API(void)
 545 JS_DumpPCCounts(JSContext *cx, JSScript *script);
 546
 547 extern JS_PUBLIC_API(void)
 548 JS_DumpCompartmentPCCounts(JSContext *cx);
 549
 550 extern JS_PUBLIC_API(JSObject *)
 551 JS_UnwrapObject(JSObject *obj);
 552
 553 extern JS_PUBLIC_API(JSObject *)
 554 JS_UnwrapObjectAndInnerize(JSObject *obj);
 555
 556 /* Call the context debug handler on the topmost scripted frame. */
 557 extern JS_FRIEND_API(JSBool)
 558 js_CallContextDebugHandler(JSContext *cx);
 559
 560 JS_END_EXTERN_C
 561
 562 #endif /* jsdbgapi_h___ */