index.rst (23895B)
1 ======== 2 Debugger 3 ======== 4 5 The Debugger Object 6 ******************* 7 8 When called as a constructor, the ``Debugger`` object creates a new ``Debugger`` instance. 9 10 11 ``new Debugger([global, …])`` 12 Create a debugger object, and apply its :ref:`addDebuggee <debugger-api-debugger-add-debuggee>` method to each of the given *global* objects to add them as the initial debuggees. 13 14 15 Accessor Properties of the Debugger Prototype Object 16 ---------------------------------------------------- 17 18 A ``Debugger`` instance inherits the following accessor properties from its prototype: 19 20 21 ``enabled`` 22 23 A boolean value indicating whether this ``Debugger`` instance’s handlers, breakpoints, and the like are currently enabled. It is an accessor property with a getter and setter: assigning to it enables or disables this ``Debugger`` instance; reading it produces true if the instance is enabled, or false otherwise. This property is initially ``true`` in a freshly created ``Debugger`` instance. 24 25 This property gives debugger code a single point of control for disentangling itself from the debuggee, regardless of what sort of events or handlers or “points” we add to the interface. 26 27 ``allowUnobservedAsmJS`` 28 29 A boolean value indicating whether asm.js code running inside this ``Debugger`` instance’s debuggee globals is invisible to Debugger API handlers and breakpoints. Setting this to ``false`` inhibits the ahead-of-time asm.js compiler and forces asm.js code to run as normal JavaScript. This is an accessor property with a getter and setter. It is initially ``false`` in a freshly created ``Debugger`` instance. 30 31 Setting this flag to ``true`` is intended for uses of subsystems of the Debugger API (e.g, :doc:`Debugger.Source <../debugger.source/index>`) for purposes other than step debugging a target JavaScript program. 32 33 ``allowWasmBinarySource`` 34 35 A boolean value indicating whether WebAssembly sources will be available in binary form. The WebAssembly text generation will be disabled. 36 37 ``collectCoverageInfo`` 38 39 A boolean value indicating whether code coverage should be enabled inside each debuggee of this ``Debugger`` instance. Changing this flag value will recompile all JIT code to add or remove code coverage instrumentation. Changing this flag when any frame of the debuggee is currently active on the stack will produce an exception. 40 41 Setting this to ``true`` enables code coverage instrumentation, which can be accessed via the :doc:`Debugger.Script <../debugger.script/index>` ``getOffsetsCoverage`` function. In some cases, the code coverage might expose information which pre-date the modification of this flag. Code coverage reports are monotone, thus one can take a snapshot when the Debugger is enabled, and output the difference. 42 43 Setting this to ``false`` prevents this ``Debugger`` instance from requiring any code coverage instrumentation, but it does not guarantee that the instrumentation is not present. 44 45 ``uncaughtExceptionHook`` 46 47 Either ``null`` or a function that SpiderMonkey calls when a call to a debug event handler, breakpoint handler, or similar function throws some exception, which we refer to as *debugger-exception* here. Exceptions thrown in the debugger are not propagated to debuggee code; instead, SpiderMonkey calls this function, passing *debugger-exception* as its sole argument and the ``Debugger`` instance as the ``this`` value. This function should return a resumption value, which determines how the debuggee should continue. 48 49 If the uncaught exception hook itself throws an exception, *uncaught-hook-exception*, SpiderMonkey throws a new error object, *confess-to-debuggee-exception*, to the debuggee whose message blames the debugger, and includes textual descriptions of *uncaught-hook-exception* and the original *debugger-exception*. 50 51 If ``uncaughtExceptionHook``’s value is ``null``, SpiderMonkey throws an exception to the debuggee whose message blames the debugger, and includes a textual description of *debugger-exception*. 52 53 Assigning anything other than a callable value or ``null`` to this property throws a ``TypeError`` exception. 54 55 (This is not an ideal way to handle debugger bugs, but the hope here is that some sort of backstop, even if imperfect, will make life easier for debugger developers. For example, an uncaught exception hook may have access to browser-level features like the ``alert`` function, which this API’s implementation does not, making it possible to present debugger errors to the developer in a way suited to the context.) 56 57 58 Debugger Handler Functions 59 ************************** 60 61 Each ``Debugger`` instance inherits accessor properties with which you can store handler functions for SpiderMonkey to call when given events occur in debuggee code. 62 63 When one of the events described below occurs in debuggee code, the engine pauses the debuggee and calls the corresponding debugging handler on each ``Debugger`` instance that is observing the debuggee. The handler functions receive the ``Debugger`` instance as their ``this`` value. Most handler functions can return a resumption value indicating how the debuggee’s execution should proceed. 64 65 On a new ``Debugger`` instance, each of these properties is initially ``undefined``. Any value assigned to a debugging handler must be either a function or ``undefined``; otherwise a ``TypeError`` is thrown. 66 67 Handler functions run in the same thread in which the event occurred. They run in the compartment to which they belong, not in a debuggee compartment. 68 69 70 ``onNewScript(script, global)`` 71 72 New code, represented by the :doc:`Debugger.Script <../debugger.script/index>` instance *script*, has been loaded in the scope of the debuggees. 73 74 This method’s return value is ignored. 75 76 ``onNewPromise(promise)`` 77 78 A new Promise object, referenced by the :doc:`Debugger.Object <../debugger.object/index>` instance *promise*, has been allocated in the scope of the debuggees. The Promise’s allocation stack can be obtained using the *promiseAllocationStack* accessor property of the :doc:`Debugger.Object <../debugger.object/index>` instance *promise*. 79 80 This handler method should return a resumption value specifying how the debuggee’s execution should proceed. However, note that a ``{ return: value }`` resumption value is treated like ``undefined`` (“continue normally”); *value* is ignored. 81 82 ``onPromiseSettled(promise)`` 83 84 A Promise object, referenced by the :doc:`Debugger.Object <../debugger.object/index>` instance *promise* that was allocated within a debuggee scope, has settled (either fulfilled or rejected). The Promise’s state, fulfillment or rejection value, and the allocation and resolution stacks can be obtained using the Promise-related accessor properties of the :doc:`Debugger.Object <../debugger.object/index>` instance *promise*. 85 86 This handler method should return a resumption value specifying how the debuggee’s execution should proceed. However, note that a ``{ return: value }`` resumption value is treated like ``undefined`` (“continue normally”); *value* is ignored. 87 88 ``onDebuggerStatement(frame)`` 89 90 Debuggee code has executed a *debugger* statement in *frame*. This method should return a resumption value specifying how the debuggee’s execution should proceed. 91 92 ``onEnterFrame(frame)`` 93 94 The stack *frame* is about to begin executing code. (Naturally, *frame* is currently the youngest :doc:`visible frame <../debugger.frame/index>`.) This method should return a resumption value specifying how the debuggee’s execution should proceed. 95 96 SpiderMonkey only calls ``onEnterFrame`` to report :ref:`visible <debugger-api-debugger-frame-visible-frames>`, non-``"debugger"`` frames. 97 98 ``onExceptionUnwind(frame, value)`` 99 100 The exception *value* has been thrown, and has propagated to *frame*; *frame* is the youngest remaining stack frame, and is a debuggee frame. This method should return a resumption value specifying how the debuggee’s execution should proceed. If it returns ``undefined``, the exception continues to propagate as normal: if control in ``frame`` is in a ``try`` block, control jumps to the corresponding ``catch`` or ``finally`` block; otherwise, *frame* is popped, and the exception propagates to *frame* caller. 101 102 When an exception’s propagation causes control to enter a ``finally`` block, the exception is temporarily set aside. If the ``finally`` block finishes normally, the exception resumes propagation, and the debugger’s ``onExceptionUnwind`` handler is called again, in the same frame. (The other possibility is for the ``finally`` block to exit due to a ``return``, ``continue``, or ``break`` statement, or a new exception. In those cases the old exception does not continue to propagate; it is discarded.) 103 104 This handler is not called when unwinding a frame due to an over-recursion or out-of-memory exception. 105 106 ``sourceHandler(ASuffusionOfYellow)`` 107 108 This method is never called. If it is ever called, a contradiction has been proven, and the debugger is free to assume that everything is true. 109 110 ``onError(frame, report)`` 111 112 SpiderMonkey is about to report an error in *frame*. *Report* is an object describing the error, with the following properties: 113 114 115 ``message`` 116 The fully formatted error message. 117 ``file`` 118 If present, the source file name, URL, etc. (If this property is present, the *line* property will be too, and vice versa.) 119 ``line`` 120 If present, the source line number at which the error occurred. 121 ``lineText`` 122 If present, this is the source code of the offending line. 123 ``offset`` 124 The index of the character within lineText at which the error occurred. 125 ``warning`` 126 Present and true if this is a warning; absent otherwise. 127 ``strict`` 128 Present and true if this error or warning is due to the strict option (not to be confused with ES strict mode) 129 ``exception`` 130 Present and true if an exception will be thrown; absent otherwise. 131 ``arguments`` 132 An array of strings, representing the arguments substituted into the error message. 133 134 135 This method’s return value is ignored. 136 137 ``onNewGlobalObject(global)`` 138 139 A new global object, *global*, has been created. 140 141 This handler method should return a resumption value specifying how the debuggee’s execution should proceed. However, note that a ``{ return: value }`` resumption value is treated like ``undefined`` (“continue normally”); *value* is ignored. (Allowing the handler to substitute its own value for the new global object doesn’t seem useful.) 142 143 This handler method is only available to debuggers running in privileged code (“chrome”, in Firefox). Most functions provided by this ``Debugger`` API observe activity in only those globals that are reachable by the API’s user, thus imposing capability-based restrictions on a ``Debugger``’s reach. However, the ``onNewGlobalObject`` method allows the API user to monitor all global object creation that occurs anywhere within the JavaScript system (the “JSRuntime”, in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, ``onNewGlobalObject`` is only available to privileged code. 144 145 146 Function Properties of the Debugger Prototype Object 147 **************************************************** 148 149 The functions described below may only be called with a ``this`` value referring to a ``Debugger`` instance; they may not be used as methods of other kinds of objects. 150 151 .. _debugger-api-debugger-add-debuggee: 152 153 ``addDebuggee(global)`` 154 155 Add the global object designated by *global* to the set of global objects this ``Debugger`` instance is debugging. If the designated global is already a debuggee, this has no effect. Return this ``Debugger`` :doc:`Debugger.Object <../debugger.object/index>` instance referring to the designated global. 156 157 The value *global* may be any of the following: 158 159 - A global object. 160 161 - An HTML5 ``WindowProxy`` object (an “outer window”, in Firefox terminology), which is treated as if the ``Window`` object of the browsing context’s active document (the “inner window”) were passed. 162 163 - A cross-compartment wrapper of an object; we apply the prior rules to the wrapped object. 164 165 - A :doc:`Debugger.Object <../debugger.object/index>` instance belonging to this ``Debugger`` instance; we apply the prior rules to the referent. 166 167 - Any other sort of value is treated as a ``TypeError``. (Note that each rule is only applied once in the process of resolving a given *global* argument. Thus, for example, a :doc:`Debugger.Object <../debugger.object/index>` referring to a second :doc:`Debugger.Object <../debugger.object/index>` which refers to a global does not designate that global for the purposes of this function.) 168 169 170 The global designated by *global* must be in a different compartment than this ``Debugger`` instance itself. If adding the designated global’s compartment would create a cycle of debugger and debuggee compartments, this method throws an error. 171 172 This method returns the :doc:`Debugger.Object <../debugger.object/index>` instance whose referent is the designated global object. 173 174 The ``Debugger`` instance does not hold a strong reference to its debuggee globals: if a debuggee global is not otherwise reachable, then it is dropped from the ``Debugger`` set of debuggees. (Naturally, the :doc:`Debugger.Object <../debugger.object/index>` instance this method returns does hold a strong reference to the added global.) 175 176 If this debugger is :ref:`tracking allocation sites <debugger-api-debugger-memory-tracking-allocation-sites>` and cannot track allocation sites for *global*, this method throws an ``Error``. 177 178 ``addAllGlobalsAsDebuggees()`` 179 180 This method is like :ref:`addDebuggee <debugger-api-debugger-add-debuggee>`, but adds all the global objects from all compartments to this ``Debugger`` instance’s set of debuggees. Note that it skips this debugger’s compartment. 181 182 If this debugger is :ref:`tracking allocation sites <debugger-api-debugger-memory-tracking-allocation-sites>` and cannot track allocation sites for some global, this method throws an ``Error``. Otherwise this method returns ``undefined``. 183 184 This method is only available to debuggers running in privileged code (“chrome”, in Firefox). Most functions provided by this ``Debugger`` API observe activity in only those globals that are reachable by the API’s user, thus imposing capability-based restrictions on a ``Debugger``’s reach. However, the ``addAllGlobalsAsDebuggees`` method allows the API user to monitor all global object creation that occurs anywhere within the JavaScript system (the “JSRuntime”, in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, ``addAllGlobalsAsDebuggees`` is only available to privileged code. 185 186 ``removeDebuggee(global)`` 187 188 Remove the global object designated by *global* from this ``Debugger`` instance’s set of debuggees. Return ``undefined``. 189 190 This method interprets *global* using the same rules that :ref:`addDebuggee <debugger-api-debugger-add-debuggee>` does. 191 192 Removing a global as a debuggee from this ``Debugger`` clears all breakpoints that belong to that ``Debugger`` in that global. 193 194 ``removeAllDebuggees()`` 195 196 Remove all the global objects from this ``Debugger`` instance’s set of debuggees. Return ``undefined``. 197 198 ``hasDebuggee(global)`` 199 200 Return ``true`` if the global object designated by *global* is a debuggee of this ``Debugger`` instance. 201 202 This method interprets *global* using the same rules that :ref:`addDebuggee <debugger-api-debugger-add-debuggee>` does. 203 204 ``getDebuggees()`` 205 206 Return an array of distinct :doc:`Debugger.Object <../debugger.object/index>` instances whose referents are all the global objects this ``Debugger`` instance is debugging. 207 208 Since ``Debugger`` instances don’t hold strong references to their debuggee globals, if a debuggee global is otherwise unreachable, it may be dropped at any moment from the array this method returns. 209 210 ``getNewestFrame()`` 211 212 Return a :doc:`Debugger.Frame <../debugger.frame/index>` instance referring to the youngest :doc:`visible frame <../debugger.frame/index>` currently on the calling thread’s stack, or ``null`` if there are no visible frames on the stack. 213 214 ``findSources([query]) (not yet implemented)`` 215 216 Return an array of all :doc:`Debugger.Source <../debugger.source/index>` instances matching *query*. Each source appears only once in the array. *Query* is an object whose properties restrict which sources are returned; a source must meet all the criteria given by *query* to be returned. If *query* is omitted, we return all sources of all debuggee scripts. 217 218 *Query* may have the following properties: 219 220 ``url`` 221 The source’s ``url`` property must be equal to this value. 222 223 ``global`` 224 The source must have been evaluated in the scope of the given global object. If this property’s value is a :doc:`Debugger.Object <../debugger.object/index>` instance belonging to this ``Debugger`` instance, then its referent is used. If the object is not a global object, then the global in whose scope it was allocated is used. 225 226 Note that the result may include sources that can no longer ever be used by the debuggee: say, eval code that has finished running, or source for unreachable functions. Whether such sources appear can be affected by the garbage collector’s behavior, so this function’s result is not entirely deterministic. 227 228 ``findScripts([query])`` 229 230 Return an array of :doc:`Debugger.Script <../debugger.script/index>` instances for all debuggee scripts matching *query*. Each instance appears only once in the array. *Query* is an object whose properties restrict which scripts are returned; a script must meet all the criteria given by *query* to be returned. If *query* is omitted, we return the :doc:`Debugger.Script <../debugger.script/index>` instances for all debuggee scripts. 231 232 *Query* may have the following properties: 233 234 235 ``url`` 236 The script’s ``url`` property must be equal to this value. 237 ``source`` 238 The script’s ``source`` property must be equal to this value. 239 ``line`` 240 The script must at least partially cover the given source line. If this property is present, the ``url`` property must be present as well. 241 ``innermost`` 242 If this property is present and true, the script must be the innermost script covering the given source location; scripts of enclosing code are omitted. 243 ``global`` 244 The script must be in the scope of the given global object. If this property’s value is a :doc:`Debugger.Object <../debugger.object/index>` instance belonging to this ``Debugger`` instance, then its referent is used. If the object is not a global object, then the global in whose scope it was allocated is used. 245 246 247 All properties of *query* are optional. Passing an empty object returns all debuggee code scripts. 248 249 Note that the result may include :doc:`Debugger.Script <../debugger.script/index>` instances for scripts that can no longer ever be used by the debuggee, say, those for eval code that has finished running, or unreachable functions. Whether such scripts appear can be affected by the garbage collector’s behavior, so this function’s behavior is not entirely deterministic. 250 251 ``findObjects([query])`` 252 253 Return an array of :doc:`Debugger.Object <../debugger.object/index>` instances referring to each live object allocated in the scope of the debuggee globals that matches *query*. Each instance appears only once in the array. *Query* is an object whose properties restrict which objects are returned; an object must meet all the criteria given by *query* to be returned. If *query* is omitted, we return the :doc:`Debugger.Object <../debugger.object/index>` instances for all objects allocated in the scope of debuggee globals. 254 255 The *query* object may have the following properties: 256 257 258 ``class`` 259 If present, only return objects whose internal ``[[Class]]``’s name matches the given string. Note that in some cases, the prototype object for a given constructor has the same ``[[Class]]`` as the instances that refer to it, but cannot itself be used as a valid instance of the class. Code gathering objects by class name may need to examine them further before trying to use them. 260 261 262 All properties of *query* are optional. Passing an empty object returns all objects in debuggee globals. 263 264 Unlike ``findScripts``, this function is deterministic and will never return <a href="Debugger.Object">``Debugger.Object``s</a> referring to previously unreachable objects that had not been collected yet. 265 266 ``clearBreakpoint(handler)`` 267 268 Remove all breakpoints set in this ``Debugger`` instance that use *handler* as their handler. Note that, if breakpoints using other handler objects are set at the same location(s) as *handler*, they remain in place. 269 270 ``clearAllBreakpoints()`` 271 272 Remove all breakpoints set using this ``Debugger`` instance. 273 274 ``findAllGlobals()`` 275 276 Return an array of :doc:`Debugger.Object <../debugger.object/index>` instances referring to all the global objects present in this JavaScript instance. 277 278 The results of this call can be affected in non-deterministic ways by the details of the JavaScript implementation. The array may include :doc:`Debugger.Object <../debugger.object/index>` instances referring to global objects that are not actually reachable by the debuggee or any other code in the system. (Naturally, once the function has returned, the array’s :doc:`Debugger.Object <../debugger.object/index>` instances strongly reference the globals they refer to.) 279 280 This handler method is only available to debuggers running in privileged code (“chrome”, in Firefox). Most functions provided by this ``Debugger`` API observe activity in only those globals that are reachable by the API’s user, thus imposing capability-based restrictions on a ``Debugger``’s reach. However, ``findAllGlobals`` allows the API user to find all global objects anywhere within the JavaScript system (the “JSRuntime”, in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, ``findAllGlobals`` is only available to privileged code. 281 282 ``makeGlobalObjectReference(global)`` 283 284 Return the :doc:`Debugger.Object <../debugger.object/index>` whose referent is the global object designated by *global*, without adding the designated global as a debuggee. If *global* does not designate a global object, throw a ``TypeError``. Determine which global is designated by *global* using the same rules as <a href="Debugger#addDebuggee" title="The Debugger object: addDebuggee">``Debugger.prototype.addDebuggee``</a>. 285 286 ``adoptDebuggeeValue(value)`` 287 288 Given a debuggee value ``value`` owned by an arbitrary ``Debugger``, return an equivalent debuggee value owned by this ``Debugger``. 289 290 If ``value`` is a primitive value, return it unchanged. If ``value`` is a ``Debugger.Object`` owned by an arbitrary ``Debugger``, return an equivalent ``Debugger.Object`` owned by this ``Debugger``. Otherwise, if ``value`` is some other kind of object, and hence not a proper debuggee value, throw a TypeError instead. 291 292 293 Static methods of the Debugger Object 294 ************************************* 295 296 The functions described below are not called with a ``this`` value. 297 298 ``isCompilableUnit(source)`` 299 Given a string of source code, designated by *source*, return false if the string might become a valid JavaScript statement with the addition of more lines. Otherwise return true. The intent is to support interactive compilation - accumulate lines in a buffer until isCompilableUnit is true, then pass it to the compiler. 300 301 302 Source Metadata 303 --------------- 304 305 Generated from file: 306 js/src/doc/Debugger/Debugger.md 307 308 Watermark: 309 sha256:03b36132885e046a5f213130ba22b1139b473770f7324b842483c09ab7665f7c 310 311 Changeset: 312 `e91b2c85aacd <https://hg.mozilla.org/mozilla-central/rev/e91b2c85aacd>`_