1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/src/doc/Debugger/Debugger.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,395 @@
1.4 +# The Debugger Object
1.5 +
1.6 +When called as a constructor, the `Debugger` object creates a new
1.7 +`Debugger` instance.
1.8 +
1.9 +<code>new Debugger([<i>global</i>, ...])</code>
1.10 +: Create a debugger object, and apply its [`addDebuggee`][add] method to
1.11 + each of the given <i>global</i> objects to add them as the initial
1.12 + debuggees.
1.13 +
1.14 +## Accessor Properties of the Debugger Prototype Object
1.15 +
1.16 +A `Debugger` instance inherits the following accessor properties from
1.17 +its prototype:
1.18 +
1.19 +`enabled`
1.20 +: A boolean value indicating whether this `Debugger` instance's handlers,
1.21 + breakpoints, watchpoints, and the like are currently enabled. It is an
1.22 + accessor property with a getter and setter: assigning to it enables or
1.23 + disables this `Debugger` instance; reading it produces true if the
1.24 + instance is enabled, or false otherwise. This property is initially
1.25 + `true` in a freshly created `Debugger` instance.
1.26 +
1.27 + This property gives debugger code a single point of control for
1.28 + disentangling itself from the debuggee, regardless of what sort of
1.29 + events or handlers or "points" we add to the interface.
1.30 +
1.31 +`uncaughtExceptionHook`
1.32 +: Either `null` or a function that SpiderMonkey calls when a call to a
1.33 + debug event handler, breakpoint handler, watchpoint handler, or similar
1.34 + function throws some exception, which we refer to as
1.35 + <i>debugger-exception</i> here. Exceptions thrown in the debugger are
1.36 + not propagated to debuggee code; instead, SpiderMonkey calls this
1.37 + function, passing <i>debugger-exception</i> as its sole argument and
1.38 + the `Debugger` instance as the `this` value. This function should
1.39 + return a [resumption value][rv], which determines how the debuggee
1.40 + should continue.
1.41 +
1.42 + If the uncaught exception hook itself throws an exception,
1.43 + <i>uncaught-hook-exception</i>, SpiderMonkey throws a new error object,
1.44 + <i>confess-to-debuggee-exception</i>, to the debuggee whose message
1.45 + blames the debugger, and includes textual descriptions of
1.46 + <i>uncaught-hook-exception</i> and the original
1.47 + <i>debugger-exception</i>.
1.48 +
1.49 + If `uncaughtExceptionHook`'s value is `null`, SpiderMonkey throws an
1.50 + exception to the debuggee whose message blames the debugger, and
1.51 + includes a textual description of <i>debugger-exception</i>.
1.52 +
1.53 + Assigning anything other than a callable value or `null` to this
1.54 + property throws a `TypeError` exception.
1.55 +
1.56 + (This is not an ideal way to handle debugger bugs, but the hope here is
1.57 + that some sort of backstop, even if imperfect, will make life easier for
1.58 + debugger developers. For example, an uncaught exception hook may have
1.59 + access to browser-level features like the `alert` function, which this
1.60 + API's implementation does not, making it possible to present debugger
1.61 + errors to the developer in a way suited to the context.)
1.62 +
1.63 +
1.64 +## Debugger Handler Functions
1.65 +
1.66 +Each `Debugger` instance inherits accessor properties with which you can
1.67 +store handler functions for SpiderMonkey to call when given events occur
1.68 +in debuggee code.
1.69 +
1.70 +When one of the events described below occurs in debuggee code, the engine
1.71 +pauses the debuggee and calls the corresponding debugging handler on each
1.72 +`Debugger` instance that is observing the debuggee. The handler functions
1.73 +receive the `Debugger` instance as their `this` value. Most handler
1.74 +functions can return a [resumption value][rv] indicating how the debuggee's
1.75 +execution should proceed.
1.76 +
1.77 +On a new `Debugger` instance, each of these properties is initially
1.78 +`undefined`. Any value assigned to a debugging handler must be either a
1.79 +function or `undefined`; otherwise a `TypeError` is thrown.
1.80 +
1.81 +Handler functions run in the same thread in which the event occurred.
1.82 +They run in the compartment to which they belong, not in a debuggee
1.83 +compartment.
1.84 +
1.85 +<code>onNewScript(<i>script</i>, <i>global</i>)</code>
1.86 +: New code, represented by the [`Debugger.Script`][script] instance
1.87 + <i>script</i>, has been loaded in the scope of the debuggee global
1.88 + object <i>global</i>. <i>global</i> is a [`Debugger.Object`][object]
1.89 + instance whose referent is the global object.
1.90 +
1.91 + This method's return value is ignored.
1.92 +
1.93 +<code>onDebuggerStatement(<i>frame</i>)</code>
1.94 +: Debuggee code has executed a <i>debugger</i> statement in <i>frame</i>.
1.95 + This method should return a [resumption value][rv] specifying how the
1.96 + debuggee's execution should proceed.
1.97 +
1.98 +<code>onEnterFrame(<i>frame</i>)</code>
1.99 +: The stack frame <i>frame</i> is about to begin executing code.
1.100 + (Naturally, <i>frame</i> is currently the youngest
1.101 + [visible frame][vf].) This method should return
1.102 + a [resumption value][rv] specifying how the debuggee's execution should
1.103 + proceed.
1.104 +
1.105 + SpiderMonkey only calls `onEnterFrame` to report
1.106 + [visible][vf], non-`"debugger"` frames.
1.107 +
1.108 +<code>onThrow(<i>frame</i>, <i>value</i>) <i>(future plan)</i></code>
1.109 +: The exception <i>value</i> is being thrown by <i>frame</i>, which is
1.110 + running debuggee code. This method should return a
1.111 + [resumption value][rv] specifying how the debuggee's execution should
1.112 + proceed. If it returns `undefined`, the exception is thrown as normal.
1.113 +
1.114 + A call to the `onThrow` handler is typically followed by one or more
1.115 + calls to the `onExceptionUnwind` handler.
1.116 +
1.117 + *(pending discussion)* If the debuggee executes
1.118 + `try { throw 0; } finally { f(); }` and `f()` executes without error,
1.119 + the `onThrow` handler is called only once. The debugger is not notified
1.120 + when the exception is set aside in order to execute the `finally` block,
1.121 + nor when it is restored after the `finally` block completes normally.
1.122 +
1.123 + *(An alternative design here would be: onException(status, frame, value)
1.124 + where status is one of the strings "throw", "unwind", "catch",
1.125 + "finally", "rethrow". JS\_SaveExceptionState would trigger a "finally"
1.126 + event, JS\_RestoreExceptionState would trigger a "rethrow",
1.127 + JS\_ClearPendingException would trigger a "catch"; not sure what
1.128 + JS\_DropExceptionState or a return/throw from a finally block should
1.129 + do.)*
1.130 +
1.131 +<code>onExceptionUnwind(<i>frame</i>, <i>value</i>)</code>
1.132 +: The exception <i>value</i> has been thrown, and has propagated to
1.133 + <i>frame</i>; <i>frame</i> is the youngest remaining stack frame, and is a
1.134 + debuggee frame. This method should return a [resumption value][rv]
1.135 + specifying how the debuggee's execution should proceed. If it returns
1.136 + `undefined`, the exception continues to propagate as normal: if control in
1.137 + `frame` is in a `try` block, control jumps to the corresponding `catch` or
1.138 + `finally` block; otherwise, <i>frame</i> is popped, and the exception
1.139 + propagates to <i>frame</i>'s caller.
1.140 +
1.141 + When an exception's propagation causes control to enter a `finally`
1.142 + block, the exception is temporarily set aside. If the `finally` block
1.143 + finishes normally, the exception resumes propagation, and the debugger's
1.144 + `onExceptionUnwind` handler is called again, in the same frame. (The
1.145 + other possibility is for the `finally` block to exit due to a `return`,
1.146 + `continue`, or `break` statement, or a new exception. In those cases the
1.147 + old exception does not continue to propagate; it is discarded.)
1.148 +
1.149 +<code>sourceHandler(<i>ASuffusionOfYellow</i>)</code>
1.150 +: This method is never called. If it is ever called, a contradiction has
1.151 + been proven, and the debugger is free to assume that everything is true.
1.152 +
1.153 +<code>onError(<i>frame</i>, <i>report</i>)</code>
1.154 +: SpiderMonkey is about to report an error in <i>frame</i>. <i>Report</i>
1.155 + is an object describing the error, with the following properties:
1.156 +
1.157 + `message`
1.158 + : The fully formatted error message.
1.159 +
1.160 + `file`
1.161 + : If present, the source file name, URL, etc. (If this property is
1.162 + present, the <i>line</i> property will be too, and vice versa.)
1.163 +
1.164 + `line`
1.165 + : If present, the source line number at which the error occurred.
1.166 +
1.167 + `lineText`
1.168 + : If present, this is the source code of the offending line.
1.169 +
1.170 + `offset`
1.171 + : The index of the character within lineText at which the error occurred.
1.172 +
1.173 + `warning`
1.174 + : Present and true if this is a warning; absent otherwise.
1.175 +
1.176 + `strict`
1.177 + : Present and true if this error or warning is due to the strict option
1.178 + (not to be confused with ES strict mode)
1.179 +
1.180 + `exception`
1.181 + : Present and true if an exception will be thrown; absent otherwise.
1.182 +
1.183 + `arguments`
1.184 + : An array of strings, representing the arguments substituted into the
1.185 + error message.
1.186 +
1.187 + This method's return value is ignored.
1.188 +
1.189 +`onNewGlobalObject(global)`
1.190 +: A new global object, <i>global</i>, has been created. The application
1.191 + embedding the JavaScript implementation may provide details about what
1.192 + kind of global it is via <code><i>global</i>.hostAnnotations</code>.
1.193 +
1.194 + This handler method should return a [resumption value][rv] specifying how
1.195 + the debuggee's execution should proceed. However, note that a <code>{ return:
1.196 + <i>value</i> }</code> resumption value is treated like `undefined` ("continue
1.197 + normally"); <i>value</i> is ignored. (Allowing the handler to substitute
1.198 + its own value for the new global object doesn't seem useful.)
1.199 +
1.200 + This handler method is only available to debuggers running in privileged
1.201 + code ("chrome", in Firefox). Most functions provided by this `Debugger`
1.202 + API observe activity in only those globals that are reachable by the
1.203 + API's user, thus imposing capability-based restrictions on a
1.204 + `Debugger`'s reach. However, the `onNewGlobalObject` method allows the
1.205 + API user to monitor all global object creation that occurs anywhere
1.206 + within the JavaScript system (the "JSRuntime", in SpiderMonkey terms),
1.207 + thereby escaping the capability-based limits. For this reason,
1.208 + `onNewGlobalObject` is only available to privileged code.
1.209 +
1.210 +
1.211 +
1.212 +## Function Properties of the Debugger Prototype Object
1.213 +
1.214 +The functions described below may only be called with a `this` value
1.215 +referring to a `Debugger` instance; they may not be used as methods of
1.216 +other kinds of objects.
1.217 +
1.218 +<code id="addDebuggee">addDebuggee(<i>global</i>)</code>
1.219 +: Add the global object designated by <i>global</i> to the set of global
1.220 + objects this `Debugger` instance is debugging. If the designated global
1.221 + is already a debuggee, this has no effect. Return this `Debugger`'s
1.222 + [`Debugger.Object`][object] instance referring to the designated global.
1.223 +
1.224 + The value <i>global</i> may be any of the following:
1.225 +
1.226 + * A global object.
1.227 +
1.228 + * An HTML5 `WindowProxy` object (an "outer window", in Firefox
1.229 + terminology), which is treated as if the `Window` object of the
1.230 + browsing context's active document (the "inner window") were passed.
1.231 +
1.232 + * A cross-compartment wrapper of an object; we apply the prior rules to
1.233 + the wrapped object.
1.234 +
1.235 + * A [`Debugger.Object`][object] instance belonging to this `Debugger` instance;
1.236 + we apply the prior rules to the referent.
1.237 +
1.238 + * Any other sort of value is treated as a `TypeError`. (Note that each
1.239 + rule is only applied once in the process of resolving a given
1.240 + <i>global</i> argument. Thus, for example, a [`Debugger.Object`][object]
1.241 + referring to a second [`Debugger.Object`][object] which refers to a global does
1.242 + not designate that global for the purposes of this function.)
1.243 +
1.244 + The global designated by <i>global</i> must be in a different
1.245 + compartment than this `Debugger` instance itself. If adding the
1.246 + designated global's compartment would create a cycle of debugger and
1.247 + debuggee compartments, this method throws an error.
1.248 +
1.249 + This method returns the [`Debugger.Object`][object] instance whose referent is
1.250 + the designated global object.
1.251 +
1.252 + The `Debugger` instance does not hold a strong reference to its
1.253 + debuggee globals: if a debuggee global is not otherwise reachable, then
1.254 + it is dropped from the `Debugger`'s set of debuggees. (Naturally, the
1.255 + [`Debugger.Object`][object] instance this method returns does hold a strong
1.256 + reference to the added global.)
1.257 +
1.258 +<code>removeDebuggee(<i>global</i>)</code>
1.259 +: Remove the global object designated by <i>global</i> from this
1.260 + `Debugger` instance's set of debuggees. Return `undefined`.
1.261 +
1.262 + This method interprets <i>global</i> using the same rules that
1.263 + [`addDebuggee`][add] does.
1.264 +
1.265 +<code>hasDebuggee(<i>global</i>)</code>
1.266 +: Return `true` if the global object designated by <i>global</i> is a
1.267 + debuggee of this `Debugger` instance.
1.268 +
1.269 + This method interprets <i>global</i> using the same rules that
1.270 + [`addDebuggee`][add] does.
1.271 +
1.272 +`getDebuggees()`
1.273 +: Return an array of distinct [`Debugger.Object`][object] instances whose referents
1.274 + are all the global objects this `Debugger` instance is debugging.
1.275 +
1.276 + Since `Debugger` instances don't hold strong references to their
1.277 + debuggee globals, if a debuggee global is otherwise unreachable, it may
1.278 + be dropped at any moment from the array this method returns.
1.279 +
1.280 +`getNewestFrame()`
1.281 +: Return a [`Debugger.Frame`][frame] instance referring to the youngest
1.282 + [visible frame][vf] currently on the calling thread's stack, or `null`
1.283 + if there are no visible frames on the stack.
1.284 +
1.285 +<code>findSources([<i>query</i>]) <i>(not yet implemented)</i></code>
1.286 +: Return an array of all [`Debugger.Source`][source] instances matching
1.287 + <i>query</i>. Each source appears only once in the array. <i>Query</i>
1.288 + is an object whose properties restrict which sources are returned; a
1.289 + source must meet all the criteria given by <i>query</i> to be returned.
1.290 + If <i>query</i> is omitted, we return all sources of all debuggee
1.291 + scripts.
1.292 +
1.293 + <i>Query</i> may have the following properties:
1.294 +
1.295 + `url`
1.296 + : The source's `url` property must be equal to this value.
1.297 +
1.298 + `global`
1.299 + : The source must have been evaluated in the scope of the given global
1.300 + object. If this property's value is a [`Debugger.Object`][object] instance
1.301 + belonging to this `Debugger` instance, then its referent is used. If the
1.302 + object is not a global object, then the global in whose scope it was
1.303 + allocated is used.
1.304 +
1.305 + Note that the result may include sources that can no longer ever be
1.306 + used by the debuggee: say, eval code that has finished running, or
1.307 + source for unreachable functions. Whether such sources appear can be
1.308 + affected by the garbage collector's behavior, so this function's result
1.309 + is not entirely deterministic.
1.310 +
1.311 +<code>findScripts([<i>query</i>])</code>
1.312 +: Return an array of [`Debugger.Script`][script] instances for all debuggee scripts
1.313 + matching <i>query</i>. Each instance appears only once in the array.
1.314 + <i>Query</i> is an object whose properties restrict which scripts are
1.315 + returned; a script must meet all the criteria given by <i>query</i> to
1.316 + be returned. If <i>query</i> is omitted, we return the [`Debugger.Script`][script]
1.317 + instances for all debuggee scripts.
1.318 +
1.319 + <i>Query</i> may have the following properties:
1.320 +
1.321 + `url`
1.322 + : The script's `url` property must be equal to this value.
1.323 +
1.324 + `source` <i>(not yet implemented)</i>
1.325 + : The script's `source` property must be equal to this value.
1.326 +
1.327 + `line`
1.328 + : The script must at least partially cover the given source line. If this
1.329 + property is present, the `url` property must be present as well.
1.330 +
1.331 + `column`
1.332 + : The script must include given column on the line given by the `line`
1.333 + property. If this property is present, the `url` and `line` properties
1.334 + must both be present as well.
1.335 +
1.336 + `innermost`
1.337 + : If this property is present and true, the script must be the innermost
1.338 + script covering the given source location; scripts of enclosing code are
1.339 + omitted.
1.340 +
1.341 + `global`
1.342 + : The script must be in the scope of the given global object. If this
1.343 + property's value is a [`Debugger.Object`][object] instance belonging to this
1.344 + `Debugger` instance, then its referent is used. If the object is not a
1.345 + global object, then the global in whose scope it was allocated is used.
1.346 +
1.347 + All properties of <i>query</i> are optional. Passing an empty object
1.348 + returns all debuggee code scripts.
1.349 +
1.350 + Note that the result may include [`Debugger.Script`][script] instances for
1.351 + scripts that can no longer ever be used by the debuggee, say, those for
1.352 + eval code that has finished running, or unreachable functions. Whether
1.353 + such scripts appear can be affected by the garbage collector's
1.354 + behavior, so this function's behavior is not entirely deterministic.
1.355 +
1.356 +<code>clearBreakpoint(<i>handler</i>)</code>
1.357 +: Remove all breakpoints set in this `Debugger` instance that use
1.358 + <i>handler</i> as their handler. Note that, if breakpoints using other
1.359 + handler objects are set at the same location(s) as <i>handler</i>, they
1.360 + remain in place.
1.361 +
1.362 +`clearAllBreakpoints()`
1.363 +: Remove all breakpoints set using this `Debugger` instance.
1.364 +
1.365 +`clearAllWatchpoints()` <i>(future plan)</i>
1.366 +: Clear all watchpoints owned by this `Debugger` instance.
1.367 +
1.368 +`findAllGlobals()`
1.369 +: Return an array of [`Debugger.Object`][object] instances referring to all the
1.370 + global objects present in this JavaScript instance. The application may
1.371 + provide details about what kind of globals they are via the
1.372 + [`Debugger.Object`][object] instances' `hostAnnotations` accessors.
1.373 +
1.374 + The results of this call can be affected in non-deterministic ways by
1.375 + the details of the JavaScript implementation. The array may include
1.376 + [`Debugger.Object`][object] instances referring to global objects that are not
1.377 + actually reachable by the debuggee or any other code in the system.
1.378 + (Naturally, once the function has returned, the array's
1.379 + [`Debugger.Object`][object] instances strongly reference the globals they refer
1.380 + to.)
1.381 +
1.382 + This handler method is only available to debuggers running in privileged
1.383 + code ("chrome", in Firefox). Most functions provided by this `Debugger`
1.384 + API observe activity in only those globals that are reachable by the
1.385 + API's user, thus imposing capability-based restrictions on a
1.386 + `Debugger`'s reach. However, `findAllGlobals` allows the API user to
1.387 + find all global objects anywhere within the JavaScript system (the
1.388 + "JSRuntime", in SpiderMonkey terms), thereby escaping the
1.389 + capability-based limits. For this reason, `findAllGlobals` is only
1.390 + available to privileged code.
1.391 +
1.392 +<code>makeGlobalObjectReference(<i>global</i>)</code>
1.393 +: Return the [`Debugger.Object`][object] whose referent is the global object
1.394 + designated by <i>global</i>, without adding the designated global as a
1.395 + debuggee. If <i>global</i> does not designate a global object, throw a
1.396 + `TypeError`. Determine which global is designated by <i>global</i>
1.397 + using the same rules as [`Debugger.prototype.addDebuggee`][add].
1.398 +
