1# The Debugger Object 2 3When called as a constructor, the `Debugger` object creates a new 4`Debugger` instance. 5 6### `new Debugger([global, ...])` 7Create a debugger object, and apply its [`addDebuggee`][add] method to 8each of the given <i>global</i> objects to add them as the initial 9debuggees. 10 11## Accessor Properties of the Debugger Prototype Object 12 13A `Debugger` instance inherits the following accessor properties from 14its prototype: 15 16### `allowUnobservedAsmJS` 17A boolean value indicating whether asm.js code running inside this 18`Debugger` instance's debuggee globals is invisible to Debugger API 19handlers and breakpoints. Setting this to `false` inhibits the 20ahead-of-time asm.js compiler and forces asm.js code to run as normal 21JavaScript. This is an accessor property with a getter and setter. It is 22initially `false` in a freshly created `Debugger` instance. 23 24Setting this flag to `true` is intended for uses of subsystems of the 25Debugger API (e.g, [`Debugger.Source`][source]) for purposes other than 26step debugging a target JavaScript program. 27 28### `collectCoverageInfo` 29A boolean value indicating whether code coverage should be enabled inside 30each debuggee of this `Debugger` instance. Changing this flag value will 31recompile all JIT code to add or remove code coverage 32instrumentation. Changing this flag when any frame of the debuggee is 33currently active on the stack will produce an exception. 34 35Setting this to `true` enables code coverage instrumentation, which can be 36accessed via the [`Debugger.Script`][script] `getOffsetsCoverage` 37function. In some cases, the code coverage might expose information which 38pre-date the modification of this flag. Code coverage reports are monotone, 39thus one can take a snapshot when coverage first is enabled, and output the 40difference. 41 42Setting this to `false` prevents this `Debugger` instance from requiring any 43code coverage instrumentation, but it does not guarantee that the 44instrumentation is not present. 45 46### `uncaughtExceptionHook` 47Either `null` or a function that SpiderMonkey calls when a call to a 48debug event handler, breakpoint handler, or similar 49function throws some exception, which we refer to as 50<i>debugger-exception</i> here. Exceptions thrown in the debugger are 51not propagated to debuggee code; instead, SpiderMonkey calls this 52function, passing <i>debugger-exception</i> as its sole argument and 53the `Debugger` instance as the `this` value. This function should 54return a [resumption value][rv], which determines how the debuggee 55should continue. 56 57If the uncaught exception hook itself throws an exception, 58<i>uncaught-hook-exception</i>, SpiderMonkey throws a new error object, 59<i>confess-to-debuggee-exception</i>, to the debuggee whose message 60blames the debugger, and includes textual descriptions of 61<i>uncaught-hook-exception</i> and the original 62<i>debugger-exception</i>. 63 64If `uncaughtExceptionHook`'s value is `null`, SpiderMonkey throws an 65exception to the debuggee whose message blames the debugger, and 66includes a textual description of <i>debugger-exception</i>. 67 68Assigning anything other than a callable value or `null` to this 69property throws a `TypeError` exception. 70 71(This is not an ideal way to handle debugger bugs, but the hope here is 72that some sort of backstop, even if imperfect, will make life easier for 73debugger developers. For example, an uncaught exception hook may have 74access to browser-level features like the `alert` function, which this 75API's implementation does not, making it possible to present debugger 76errors to the developer in a way suited to the context.) 77 78 79## Debugger Handler Functions 80 81Each `Debugger` instance inherits accessor properties with which you can 82store handler functions for SpiderMonkey to call when given events occur 83in debuggee code. 84 85When one of the events described below occurs in debuggee code, the engine 86pauses the debuggee and calls the corresponding debugging handler on each 87`Debugger` instance that is observing the debuggee. The handler functions 88receive the `Debugger` instance as their `this` value. Most handler 89functions can return a [resumption value][rv] indicating how the debuggee's 90execution should proceed. 91 92On a new `Debugger` instance, each of these properties is initially 93`undefined`. Any value assigned to a debugging handler must be either a 94function or `undefined`; otherwise a `TypeError` is thrown. 95 96Handler functions run in the same thread in which the event occurred. 97They run in the compartment to which they belong, not in a debuggee 98compartment. 99 100### `onNewScript(script, global)` 101New code, represented by the [`Debugger.Script`][script] instance 102<i>script</i>, has been loaded in the scope of the debuggees. 103 104Since each function has its own [`Debugger.Script`][script], separate from 105the top-level code or function that encloses it, loading JavaScript code 106typically introduces not just a single script, but a tree of scripts 107representing the top-level code and any functions it includes. The 108`onNewScript` hook reports only the root script of such a tree. If 109necessary, the handler function can use the scripts' `getChildScripts` 110method to walk the tree and obtain all the newly introduced scripts. 111 112This method's return value is ignored. 113 114### `onNewPromise(promise)` 115A new Promise object, referenced by the [`Debugger.Object`][object] instance 116*promise*, has been allocated in the scope of the debuggees. The Promise's 117allocation stack can be obtained using the *promiseAllocationStack* 118accessor property of the [`Debugger.Object`][object] instance *promise*. 119 120This handler method should return a [resumption value][rv] specifying how 121the debuggee's execution should proceed. However, note that a <code>{ 122return: <i>value</i> }</code> resumption value is treated like `undefined` 123("continue normally"); <i>value</i> is ignored. 124 125### `onPromiseSettled(promise)` 126A Promise object, referenced by the [`Debugger.Object`][object] instance 127*promise* that was allocated within a debuggee scope, has settled (either 128fulfilled or rejected). The Promise's state, fulfillment or rejection 129value, and the allocation and resolution stacks can be obtained using the 130Promise-related accessor properties of the [`Debugger.Object`][object] 131instance *promise*. 132 133This handler method should return a [resumption value][rv] specifying how 134the debuggee's execution should proceed. However, note that a <code>{ 135return: <i>value</i> }</code> resumption value is treated like `undefined` 136("continue normally"); <i>value</i> is ignored. 137 138### `onDebuggerStatement(frame)` 139Debuggee code has executed a <i>debugger</i> statement in <i>frame</i>. 140This method should return a [resumption value][rv] specifying how the 141debuggee's execution should proceed. 142 143### `onEnterFrame(frame)` 144The stack frame <i>frame</i> is about to begin executing code. 145(Naturally, <i>frame</i> is currently the youngest 146[visible frame][vf].) This method should return 147a [resumption value][rv] specifying how the debuggee's execution should 148proceed. 149 150SpiderMonkey only calls `onEnterFrame` to report 151[visible][vf], non-`"debugger"` frames. 152 153### `onNativeCall(callee, reason)` 154A call to a native function is being made from a debuggee realm. 155<i>callee</i> is a [`Debugger.Object`] for the function being called, and 156<i>reason</i> is a string describing the reason the call was made, and 157has one of the following values: 158 159`get`: The native is the getter for a property which is being accessed. 160`set`: The native is the setter for a property being written to. 161`call`: Any call not fitting into the above categories. 162 163This method should return a [resumption value][rv] specifying how the 164debuggee's execution should proceed. 165 166SpiderMonkey only calls `onNativeCall` hooks when execution is inside a 167debugger evaluation associated with the debugger that has the `onNativeCall` 168hook. Such evaluation methods include `Debugger.Object.executeInGlobal`, 169`Debugger.Frame.eval`, and associated methods. 170 171Separately, any Debugger hooks triggered during calls to 172`Debugger.Object.executeInGlobal`, `Debugger.Frame.eval`, and associated methods 173will only be triggered on Debugger objects owned by the Debugger performing 174the evaluation. 175 176### `onExceptionUnwind(frame, value)` 177The exception <i>value</i> has been thrown, and has propagated to 178<i>frame</i>; <i>frame</i> is the youngest remaining stack frame, and is a 179debuggee frame. This method should return a [resumption value][rv] 180specifying how the debuggee's execution should proceed. If it returns 181`undefined`, the exception continues to propagate as normal: if control in 182`frame` is in a `try` block, control jumps to the corresponding `catch` or 183`finally` block; otherwise, <i>frame</i> is popped, and the exception 184propagates to <i>frame</i>'s caller. 185 186When an exception's propagation causes control to enter a `finally` 187block, the exception is temporarily set aside. If the `finally` block 188finishes normally, the exception resumes propagation, and the debugger's 189`onExceptionUnwind` handler is called again, in the same frame. (The 190other possibility is for the `finally` block to exit due to a `return`, 191`continue`, or `break` statement, or a new exception. In those cases the 192old exception does not continue to propagate; it is discarded.) 193 194This handler is not called when unwinding a frame due to an over-recursion 195or out-of-memory exception. 196 197### `sourceHandler(ASuffusionOfYellow)` 198This method is never called. If it is ever called, a contradiction has 199been proven, and the debugger is free to assume that everything is true. 200 201### `onError(frame, report)` 202SpiderMonkey is about to report an error in <i>frame</i>. <i>Report</i> 203is an object describing the error, with the following properties: 204 205* `message` 206 The fully formatted error message. 207 208* `file` 209 If present, the source file name, URL, etc. (If this property is 210 present, the <i>line</i> property will be too, and vice versa.) 211 212* `line` 213 If present, the source line number at which the error occurred. 214 215* `lineText` 216 If present, this is the source code of the offending line. 217 218* `offset` 219 The index of the character within lineText at which the error occurred. 220 221* `warning` 222 Present and true if this is a warning; absent otherwise. 223 224* `strict` 225 Present and true if this error or warning is due to the strict option 226 (not to be confused with ES strict mode) 227 228* `exception` 229 Present and true if an exception will be thrown; absent otherwise. 230 231* `arguments` 232 An array of strings, representing the arguments substituted into the 233 error message. 234 235This method's return value is ignored. 236 237### `onNewGlobalObject(global)` 238A new global object, <i>global</i>, has been created. 239 240This handler method should return a [resumption value][rv] specifying how 241the debuggee's execution should proceed. However, note that a <code>{ return: 242<i>value</i> }</code> resumption value is treated like `undefined` ("continue 243normally"); <i>value</i> is ignored. (Allowing the handler to substitute 244its own value for the new global object doesn't seem useful.) 245 246This handler method is only available to debuggers running in privileged 247code ("chrome", in Firefox). Most functions provided by this `Debugger` 248API observe activity in only those globals that are reachable by the 249API's user, thus imposing capability-based restrictions on a 250`Debugger`'s reach. However, the `onNewGlobalObject` method allows the 251API user to monitor all global object creation that occurs anywhere 252within the JavaScript system (the "JSRuntime", in SpiderMonkey terms), 253thereby escaping the capability-based limits. For this reason, 254`onNewGlobalObject` is only available to privileged code. 255 256Note that, even though the presence of a `Debugger`'s `onNewGlobalObject` 257hook can have arbitrary side effects, the garbage collector does not 258consider the presence of the hook sufficient reason to keep the `Debugger` 259alive. Thus, the behavior of code that uses `onNewGlobalObject` on unrooted 260`Debugger`s may be affected by the garbage collector's activity, and 261is not entirely deterministic. 262 263 264## Function Properties of the Debugger Prototype Object 265 266The functions described below may only be called with a `this` value 267referring to a `Debugger` instance; they may not be used as methods of 268other kinds of objects. 269 270### `addDebuggee(global)` 271Add the global object designated by <i>global</i> to the set of global 272objects this `Debugger` instance is debugging. If the designated global 273is already a debuggee, this has no effect. Return this `Debugger`'s 274[`Debugger.Object`][object] instance referring to the designated global. 275 276The value <i>global</i> may be any of the following: 277 278* A global object. 279 280* An HTML5 `WindowProxy` object (an "outer window", in Firefox 281 terminology), which is treated as if the `Window` object of the 282 browsing context's active document (the "inner window") were passed. 283 284* A cross-compartment wrapper of an object; we apply the prior rules to 285 the wrapped object. 286 287* A [`Debugger.Object`][object] instance belonging to this `Debugger` instance; 288 we apply the prior rules to the referent. 289 290* Any other sort of value is treated as a `TypeError`. (Note that each 291 rule is only applied once in the process of resolving a given 292 <i>global</i> argument. Thus, for example, a [`Debugger.Object`][object] 293 referring to a second [`Debugger.Object`][object] which refers to a global does 294 not designate that global for the purposes of this function.) 295 296The global designated by <i>global</i> must be in a different 297compartment than this `Debugger` instance itself. If adding the 298designated global's compartment would create a cycle of debugger and 299debuggee compartments, this method throws an error. 300 301This method returns the [`Debugger.Object`][object] instance whose referent is 302the designated global object. 303 304The `Debugger` instance does not hold a strong reference to its 305debuggee globals: if a debuggee global is not otherwise reachable, then 306it is dropped from the `Debugger`'s set of debuggees. (Naturally, the 307[`Debugger.Object`][object] instance this method returns does hold a strong 308reference to the added global.) 309 310If this debugger is [tracking allocation sites][tracking-allocs] and cannot 311track allocation sites for <i>global</i>, this method throws an `Error`. 312 313### `addAllGlobalsAsDebuggees()` 314This method is like [`addDebuggee`][add], but adds all the global 315objects from all compartments to this `Debugger` instance's set of 316debuggees. Note that it skips this debugger's compartment. 317 318If this debugger is [tracking allocation sites][tracking-allocs] and cannot 319track allocation sites for some global, this method throws an `Error`. 320Otherwise this method returns `undefined`. 321 322This method is only available to debuggers running in privileged 323code ("chrome", in Firefox). Most functions provided by this `Debugger` 324API observe activity in only those globals that are reachable by the 325API's user, thus imposing capability-based restrictions on a 326`Debugger`'s reach. However, the `addAllGlobalsAsDebuggees` method 327allows the API user to monitor all global object creation that 328occurs anywhere within the JavaScript system (the "JSRuntime", in 329SpiderMonkey terms), thereby escaping the capability-based 330limits. For this reason, `addAllGlobalsAsDebuggees` is only 331available to privileged code. 332 333### `removeDebuggee(global)` 334Remove the global object designated by <i>global</i> from this 335`Debugger` instance's set of debuggees. Return `undefined`. 336 337This method interprets <i>global</i> using the same rules that 338[`addDebuggee`][add] does. 339 340Removing a global as a debuggee from this `Debugger` clears all breakpoints 341that belong to that `Debugger` in that global. 342 343### `removeAllDebuggees()` 344Remove all the global objects from this `Debugger` instance's set 345of debuggees. Return `undefined`. 346 347### `hasDebuggee(global)` 348Return `true` if the global object designated by <i>global</i> is a 349debuggee of this `Debugger` instance. 350 351This method interprets <i>global</i> using the same rules that 352[`addDebuggee`][add] does. 353 354### `getDebuggees()` 355Return an array of distinct [`Debugger.Object`][object] instances whose referents 356are all the global objects this `Debugger` instance is debugging. 357 358Since `Debugger` instances don't hold strong references to their 359debuggee globals, if a debuggee global is otherwise unreachable, it may 360be dropped at any moment from the array this method returns. 361 362### `getNewestFrame()` 363Return a [`Debugger.Frame`][frame] instance referring to the youngest 364[visible frame][vf] currently on the calling thread's stack, or `null` 365if there are no visible frames on the stack. 366 367### `findSources()` 368Return an array of all [`Debugger.Source`][source] instances of all debuggee 369scripts. 370 371Note that the result may include sources that can no longer ever be 372used by the debuggee: say, eval code that has finished running, or 373source for unreachable functions. Whether such sources appear can be 374affected by the garbage collector's behavior, so this function's result 375is not entirely deterministic. 376 377### `findScripts([query])` 378Return an array of [`Debugger.Script`][script] instances for all debuggee scripts 379matching <i>query</i>. Each instance appears only once in the array. 380<i>Query</i> is an object whose properties restrict which scripts are 381returned; a script must meet all the criteria given by <i>query</i> to 382be returned. If <i>query</i> is omitted, we return the [`Debugger.Script`][script] 383instances for all debuggee scripts. 384 385<i>Query</i> may have the following properties: 386 387* `url` 388 389 The script's `url` property must be equal to this value. 390 391* `source` 392 393 The script's `source` property must be equal to this value. 394 395* `line` 396 397 The script must at least partially cover the given source line. If this 398 property is present, the `url` property must be present as well. 399 400* `column` 401 402 The script must include given column on the line given by the `line`property. 403 If this property is present, the `url` and `line` properties must both be 404 present as well. 405 406* `innermost` 407 408 If this property is present and true, the script must be the innermost 409 script covering the given source location; scripts of enclosing code are 410 omitted. 411 412* `global` 413 414 The script must be in the scope of the given global object. If this 415 property's value is a [`Debugger.Object`][object] instance belonging to this 416 `Debugger` instance, then its referent is used. If the object is not a 417 global object, then the global in whose scope it was allocated is used. 418 419All properties of <i>query</i> are optional. Passing an empty object 420returns all debuggee code scripts. 421 422Note that the result may include [`Debugger.Script`][script] instances for 423scripts that can no longer ever be used by the debuggee, say, those for 424eval code that has finished running, or unreachable functions. Whether 425such scripts appear can be affected by the garbage collector's 426behavior, so this function's behavior is not entirely deterministic. 427 428### `findSourceURLs()` 429 430Return an array of strings containing the URLs of all known sources that 431have been created in any debuggee realm. The array will have one entry for 432each source, so may have duplicates. The URLs for the realms are 433occasionally purged and the returned array might not be complete. 434 435### `findObjects([query])` 436Return an array of [`Debugger.Object`][object] instances referring to each 437live object allocated in the scope of the debuggee globals that matches 438*query*. Each instance appears only once in the array. *Query* is an object 439whose properties restrict which objects are returned; an object must meet 440all the criteria given by *query* to be returned. If *query* is omitted, we 441return the [`Debugger.Object`][object] instances for all objects allocated 442in the scope of debuggee globals. 443 444The *query* object may have the following properties: 445 446* `class` 447 448 If present, only return objects whose internal `[[Class]]`'s name 449 matches the given string. Note that in some cases, the prototype object 450 for a given constructor has the same `[[Class]]` as the instances that 451 refer to it, but cannot itself be used as a valid instance of the 452 class. Code gathering objects by class name may need to examine them 453 further before trying to use them. 454 455All properties of *query* are optional. Passing an empty object returns all 456objects in debuggee globals. 457 458Unlike `findScripts`, this function is deterministic and will never return 459[`Debugger.Object`s][object] referring to previously unreachable objects 460that had not been collected yet. 461 462### `clearBreakpoint(handler)` 463Remove all breakpoints set in this `Debugger` instance that use 464<i>handler</i> as their handler. Note that, if breakpoints using other 465handler objects are set at the same location(s) as <i>handler</i>, they 466remain in place. 467 468### `clearAllBreakpoints()` 469Remove all breakpoints set using this `Debugger` instance. 470 471### `findAllGlobals()` 472Return an array of [`Debugger.Object`][object] instances referring to all the 473global objects present in this JavaScript instance. 474 475The results of this call can be affected in non-deterministic ways by 476the details of the JavaScript implementation. The array may include 477[`Debugger.Object`][object] instances referring to global objects that are not 478actually reachable by the debuggee or any other code in the system. 479(Naturally, once the function has returned, the array's 480[`Debugger.Object`][object] instances strongly reference the globals they refer 481to.) 482 483This handler method is only available to debuggers running in privileged 484code ("chrome", in Firefox). Most functions provided by this `Debugger` 485API observe activity in only those globals that are reachable by the 486API's user, thus imposing capability-based restrictions on a 487`Debugger`'s reach. However, `findAllGlobals` allows the API user to 488find all global objects anywhere within the JavaScript system (the 489"JSRuntime", in SpiderMonkey terms), thereby escaping the 490capability-based limits. For this reason, `findAllGlobals` is only 491available to privileged code. 492 493### `makeGlobalObjectReference(global)` 494Return the [`Debugger.Object`][object] whose referent is the global object 495designated by <i>global</i>, without adding the designated global as a 496debuggee. If <i>global</i> does not designate a global object, throw a 497`TypeError`. Determine which global is designated by <i>global</i> 498using the same rules as [`Debugger.prototype.addDebuggee`][add]. 499 500### `adoptDebuggeeValue(value)` 501Given a debuggee value `value` owned by an arbitrary `Debugger`, return an 502equivalent debuggee value owned by this `Debugger`. 503 504If `value` is a primitive value, return it unchanged. If `value` is a 505`Debugger.Object` owned by an arbitrary `Debugger`, return an equivalent 506`Debugger.Object` owned by this `Debugger`. Otherwise, if `value` is some 507other kind of object, and hence not a proper debuggee value, throw a 508TypeError instead. 509 510### `adoptFrame(frame)` 511Given `frame` of type `Debugger.Frame` which is owned by an arbitrary 512`Debugger`, return an equivalent `Debugger.Frame` owned by this `Debugger`. 513If the `frame` is associated with a debuggee that is _not_ a debuggee of 514the adopting debugger, this method will throw. 515 516### `adoptSource(source)` 517Given `source` of type `Debugger.Source` which is owned by an arbitrary 518`Debugger`, return an equivalent `Debugger.Source` owned by this `Debugger`. 519 520## Static methods of the Debugger Object 521 522The functions described below are not called with a `this` value. 523 524### `isCompilableUnit(source)` 525: Given a string of source code, designated by <i>source</i>, return false if 526 the string might become a valid JavaScript statement with the addition of 527 more lines. Otherwise return true. The intent is to support interactive 528 compilation - accumulate lines in a buffer until isCompilableUnit is true, 529 then pass it to the compiler. 530 531[add]: #adddebuggee-global 532[source]: Debugger.Source.md 533[script]: Debugger.Script.md 534[rv]: Conventions.html#resumption-values 535[object]: Debugger.Object.md 536[vf]: Debugger.Frame.html#visible-frames 537[tracking-allocs]: Debugger.Memory.html#trackingallocationsites 538[frame]: Debugger.Frame.md 539