1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/src/doc/Debugger/Debugger.Frame.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,421 @@
1.4 +# Debugger.Frame
1.5 +
1.6 +A `Debugger.Frame` instance represents a [visible stack frame][vf]. Given a
1.7 +`Debugger.Frame` instance, you can find the script the frame is executing,
1.8 +walk the stack to older frames, find the lexical environment in which the
1.9 +execution is taking place, and so on.
1.10 +
1.11 +For a given [`Debugger`][debugger-object] instance, SpiderMonkey creates
1.12 +only one `Debugger.Frame` instance for a given visible frame. Every handler
1.13 +method called while the debuggee is running in a given frame is given the
1.14 +same frame object. Similarly, walking the stack back to a previously
1.15 +accessed frame yields the same frame object as before. Debugger code can
1.16 +add its own properties to a frame object and expect to find them later, use
1.17 +`==` to decide whether two expressions refer to the same frame, and so on.
1.18 +
1.19 +(If more than one [`Debugger`][debugger-object] instance is debugging the
1.20 +same code, each [`Debugger`][debugger-object] gets a separate
1.21 +`Debugger.Frame` instance for a given frame. This allows the code using
1.22 +each [`Debugger`][debugger-object] instance to place whatever properties it
1.23 +likes on its `Debugger.Frame` instances, without worrying about interfering
1.24 +with other debuggers.)
1.25 +
1.26 +When the debuggee pops a stack frame (say, because a function call has
1.27 +returned or an exception has been thrown from it), the `Debugger.Frame`
1.28 +instance referring to that frame becomes inactive: its `live` property
1.29 +becomes `false`, and accessing its other properties or calling its methods
1.30 +throws an exception. Note that frames only become inactive at times that
1.31 +are predictable for the debugger: when the debuggee runs, or when the
1.32 +debugger removes frames from the stack itself.
1.33 +
1.34 +Stack frames that represent the control state of generator-iterator objects
1.35 +behave in a special way, described in [Generator Frames][generator] below.
1.36 +
1.37 +
1.38 +## Visible Frames
1.39 +
1.40 +When inspecting the call stack, [`Debugger`][debugger-object] does not
1.41 +reveal all the frames that are actually present on the stack: while it does
1.42 +reveal all frames running debuggee code, it omits frames running the
1.43 +debugger's own code, and omits most frames running non-debuggee code. We
1.44 +call those stack frames a [`Debugger`][debugger-object] does reveal
1.45 +<i>visible frames</i>.
1.46 +
1.47 +A frame is a visible frame if any of the following are true:
1.48 +
1.49 +* it is running [debuggee code][dbg code];
1.50 +
1.51 +* its immediate caller is a frame running debuggee code; or
1.52 +
1.53 +* it is a [`"debugger"` frame][inv fr],
1.54 + representing the continuation of debuggee code invoked by the debugger.
1.55 +
1.56 +The "immediate caller" rule means that, when debuggee code calls a
1.57 +non-debuggee function, it looks like a call to a primitive: you see a frame
1.58 +for the non-debuggee function that was accessible to the debuggee, but any
1.59 +further calls that function makes are treated as internal details, and
1.60 +omitted from the stack trace. If the non-debuggee function eventually calls
1.61 +back into debuggee code, then those frames are visible.
1.62 +
1.63 +(Note that the debuggee is not considered an "immediate caller" of handler
1.64 +methods it triggers. Even though the debuggee and debugger share the same
1.65 +JavaScript stack, frames pushed for SpiderMonkey's calls to handler methods
1.66 +to report events in the debuggee are never considered visible frames.)
1.67 +
1.68 +
1.69 +## Invocation Functions and "debugger" Frames
1.70 +
1.71 +An <i>invocation function</i> is any function in this interface that allows
1.72 +the debugger to invoke code in the debuggee:
1.73 +`Debugger.Object.prototype.call`, `Debugger.Frame.prototype.eval`, and so
1.74 +on.
1.75 +
1.76 +While invocation functions differ in the code to be run and how to pass
1.77 +values to it, they all follow this general procedure:
1.78 +
1.79 +1. Let <i>older</i> be the youngest visible frame on the stack, or `null`
1.80 + if there is no such frame. (This is never one of the the debugger's own
1.81 + frames; those never appear as `Debugger.Frame` instances.)
1.82 +
1.83 +2. Push a `"debugger"` frame on the stack, with <i>older</i> as its
1.84 + `older` property.
1.85 +
1.86 +3. Invoke the debuggee code as appropriate for the given invocation
1.87 + function, with the `"debugger"` frame as its continuation. For example,
1.88 + `Debugger.Frame.prototype.eval` pushes an `"eval"` frame for code it
1.89 + runs, whereas `Debugger.Object.prototype.call` pushes a `"call"` frame.
1.90 +
1.91 +4. When the debuggee code completes, whether by returning, throwing an
1.92 + exception or being terminated, pop the `"debugger"` frame, and return an
1.93 + appropriate [completion value][cv] from the invocation function to the
1.94 + debugger.
1.95 +
1.96 +When a debugger calls an invocation function to run debuggee code, that
1.97 +code's continuation is the debugger, not the next debuggee code frame.
1.98 +Pushing a `"debugger"` frame makes this continuation explicit, and makes it
1.99 +easier to find the extent of the stack created for the invocation.
1.100 +
1.101 +
1.102 +## Accessor Properties of the Debugger.Frame Prototype Object
1.103 +
1.104 +A `Debugger.Frame` instance inherits the following accessor properties from
1.105 +its prototype:
1.106 +
1.107 +`type`
1.108 +: A string describing what sort of frame this is:
1.109 +
1.110 + * `"call"`: a frame running a function call. (We may not be able to obtain
1.111 + frames for calls to host functions.)
1.112 +
1.113 + * `"eval"`: a frame running code passed to `eval`.
1.114 +
1.115 + * `"global"`: a frame running global code (JavaScript that is neither of
1.116 + the above).
1.117 +
1.118 + * `"debugger"`: a frame for a call to user code invoked by the debugger
1.119 + (see the `eval` method below).
1.120 +
1.121 +`this`
1.122 +: The value of `this` for this frame (a debuggee value).
1.123 +
1.124 +`older`
1.125 +: The next-older visible frame, in which control will resume when this
1.126 + frame completes. If there is no older frame, this is `null`. (On a
1.127 + suspended generator frame, the value of this property is `null`; see
1.128 + [Generator Frames][generator].)
1.129 +
1.130 +`depth`
1.131 +: The depth of this frame, counting from oldest to youngest; the oldest
1.132 + frame has a depth of zero.
1.133 +
1.134 +`live`
1.135 +: True if the frame this `Debugger.Frame` instance refers to is still on
1.136 + the stack (or, in the case of generator-iterator objects, has not yet
1.137 + finished its iteration); false if it has completed execution or been
1.138 + popped in some other way.
1.139 +
1.140 +`script`
1.141 +: The script being executed in this frame (a [`Debugger.Script`][script]
1.142 + instance), or `null` on frames that do not represent calls to debuggee
1.143 + code. On frames whose `callee` property is not null, this is equal to
1.144 + `callee.script`.
1.145 +
1.146 +`offset`
1.147 +: The offset of the bytecode instruction currently being executed in
1.148 + `script`, or `undefined` if the frame's `script` property is `null`.
1.149 +
1.150 +`environment`
1.151 +: The lexical environment within which evaluation is taking place (a
1.152 + [`Debugger.Environment`][environment] instance), or `null` on frames
1.153 + that do not represent the evaluation of debuggee code, like calls
1.154 + non-debuggee functions, host functions or `"debugger"` frames.
1.155 +
1.156 +`callee`
1.157 +: The function whose application created this frame, as a debuggee value,
1.158 + or `null` if this is not a `"call"` frame.
1.159 +
1.160 +`generator`
1.161 +: True if this frame is a generator frame, false otherwise.
1.162 +
1.163 +`constructing`
1.164 +: True if this frame is for a function called as a constructor, false
1.165 + otherwise.
1.166 +
1.167 +`arguments`
1.168 +: The arguments passed to the current frame, or `null` if this is not a
1.169 + `"call"` frame. When non-`null`, this is an object, allocated in the
1.170 + same global as the debugger, with `Array.prototype` on its prototype
1.171 + chain, a non-writable `length` property, and properties whose names are
1.172 + array indices. Each property is a read-only accessor property whose
1.173 + getter returns the current value of the corresponding parameter. When
1.174 + the referent frame is popped, the argument value's properties' getters
1.175 + throw an error.
1.176 +
1.177 +
1.178 +## Handler Methods of Debugger.Frame Instances
1.179 +
1.180 +Each `Debugger.Frame` instance inherits accessor properties holding handler
1.181 +functions for SpiderMonkey to call when given events occur in the frame.
1.182 +
1.183 +Calls to frames' handler methods are cross-compartment, intra-thread calls:
1.184 +the call takes place in the thread to which the frame belongs, and runs in
1.185 +the compartment to which the handler method belongs.
1.186 +
1.187 +`Debugger.Frame` instances inherit the following handler method properties:
1.188 +
1.189 +`onStep`
1.190 +: This property must be either `undefined` or a function. If it is a
1.191 + function, SpiderMonkey calls it when execution in this frame makes a
1.192 + small amount of progress, passing no arguments and providing this
1.193 + `Debugger.Frame` instance as the `this`value. The function should
1.194 + return a [resumption value][rv] specifying how the debuggee's execution
1.195 + should proceed.
1.196 +
1.197 + What constitutes "a small amount of progress" varies depending on the
1.198 + implementation, but it is fine-grained enough to implement useful
1.199 + "step" and "next" behavior.
1.200 +
1.201 + If multiple [`Debugger`][debugger-object] instances each have
1.202 + `Debugger.Frame` instances for a given stack frame with `onStep`
1.203 + handlers set, their handlers are run in an unspecified order. If any
1.204 + `onStep` handler forces the frame to return early (by returning a
1.205 + resumption value other than `undefined`), any remaining debuggers'
1.206 + `onStep` handlers do not run.
1.207 +
1.208 + This property is ignored on frames that are not executing debuggee
1.209 + code, like `"call"` frames for calls to host functions and `"debugger"`
1.210 + frames.
1.211 +
1.212 +`onPop`
1.213 +: This property must be either `undefined` or a function. If it is a
1.214 + function, SpiderMonkey calls it just before this frame is popped,
1.215 + passing a [completion value][cv] indicating how this frame's execution
1.216 + completed, and providing this `Debugger.Frame` instance as the `this`
1.217 + value. The function should return a [resumption value][rv] indicating
1.218 + how execution should proceed. On newly created frames, this property's
1.219 + value is `undefined`.
1.220 +
1.221 + When an `onPop` call reports the completion of a construction call
1.222 + (that is, a function called via the `new` operator), the completion
1.223 + value passed to the handler describes the value returned by the
1.224 + function body. If this value is not an object, it may be different from
1.225 + the value produced by the `new` expression, which will be the value of
1.226 + the frame's `this` property. (In ECMAScript terms, the `onPop` handler
1.227 + receives the value returned by the `[[Call]]` method, not the value
1.228 + returned by the `[[Construct]]` method.)
1.229 +
1.230 + When a debugger handler function forces a frame to complete early, by
1.231 + returning a `{ return:... }`, `{ throw:... }`, or `null` resumption
1.232 + value, SpiderMonkey calls the frame's `onPop` handler, if any. The
1.233 + completion value passed in this case reflects the resumption value that
1.234 + caused the frame to complete.
1.235 +
1.236 + When SpiderMonkey calls an `onPop` handler for a frame that is throwing
1.237 + an exception or being terminated, and the handler returns `undefined`,
1.238 + then SpiderMonkey proceeds with the exception or termination. That is,
1.239 + an `undefined` resumption value leaves the frame's throwing and
1.240 + termination process undisturbed.
1.241 +
1.242 + <i>(Not yet implemented.)</i> When a generator frame yields a value,
1.243 + SpiderMonkey calls its `Debugger.Frame` instance's `onPop` handler
1.244 + method, if present, passing a `yield` resumption value; however, the
1.245 + `Debugger.Frame` instance remains live.
1.246 +
1.247 + If multiple [`Debugger`][debugger-object] instances each have
1.248 + `Debugger.Frame` instances for a given stack frame with `onPop`
1.249 + handlers set, their handlers are run in an unspecified order. The
1.250 + resumption value each handler returns establishes the completion value
1.251 + reported to the next handler.
1.252 +
1.253 + This property is ignored on `"debugger"` frames.
1.254 +
1.255 +`onResume`
1.256 +: This property must be either `undefined` or a function. If it is a
1.257 + function, SpiderMonkey calls it if the current frame is a generator
1.258 + frame whose execution has just been resumed. The function should return
1.259 + a [resumption value][rv] indicating how execution should proceed. On
1.260 + newly created frames, this property's value is `undefined`.
1.261 +
1.262 + If the program resumed the generator by calling its `send` method and
1.263 + passing a value, then <i>value</i> is that value. Otherwise,
1.264 + <i>value</i> is `undefined`.
1.265 +
1.266 +
1.267 +## Function Properties of the Debugger.Frame Prototype Object
1.268 +
1.269 +The functions described below may only be called with a `this` value
1.270 +referring to a `Debugger.Frame` instance; they may not be used as
1.271 +methods of other kinds of objects.
1.272 +
1.273 +<code id="eval">eval(<i>code</i>, [<i>options</i>])</code>
1.274 +: Evaluate <i>code</i> in the execution context of this frame, and return
1.275 + a [completion value][cv] describing how it completed. <i>Code</i> is a
1.276 + string. If this frame's `environment` property is `null`, throw a
1.277 + `TypeError`. All extant handler methods, breakpoints, watchpoints, and
1.278 + so on remain active during the call. This function follows the
1.279 + [invocation function conventions][inv fr].
1.280 +
1.281 + <i>Code</i> is interpreted as strict mode code when it contains a Use
1.282 + Strict Directive, or the code executing in this frame is strict mode
1.283 + code.
1.284 +
1.285 + If <i>code</i> is not strict mode code, then variable declarations in
1.286 + <i>code</i> affect the environment of this frame. (In the terms used by
1.287 + the ECMAScript specification, the `VariableEnvironment` of the
1.288 + execution context for the eval code is the `VariableEnvironment` of the
1.289 + execution context that this frame represents.) If implementation
1.290 + restrictions prevent SpiderMonkey from extending this frame's
1.291 + environment as requested, this call throws an Error exception.
1.292 +
1.293 + If given, <i>options</i> should be an object whose properties specify
1.294 + details of how the evaluation should occur. The `eval` method
1.295 + recognizes the following properties:
1.296 +
1.297 + <code>url</code>
1.298 + : The filename or URL to which we should attribute <i>code</i>. If this
1.299 + property is omitted, the URL defaults to `"debugger eval code"`.
1.300 +
1.301 + <code>lineNumber</code>
1.302 + : The line number at which the evaluated code should be claimed to begin
1.303 + within <i>url</i>.
1.304 +
1.305 +<code>evalWithBindings(<i>code</i>, <i>bindings</i>, [<i>options</i>])</code>
1.306 +: Like `eval`, but evaluate <i>code</i> in the environment of this frame,
1.307 + extended with bindings from the object <i>bindings</i>. For each own
1.308 + enumerable property of <i>bindings</i> named <i>name</i> whose value is
1.309 + <i>value</i>, include a variable in the environment in which
1.310 + <i>code</i> is evaluated named <i>name</i>, whose value is
1.311 + <i>value</i>. Each <i>value</i> must be a debuggee value. (This is not
1.312 + like a `with` statement: <i>code</i> may access, assign to, and delete
1.313 + the introduced bindings without having any effect on the
1.314 + <i>bindings</i> object.)
1.315 +
1.316 + This method allows debugger code to introduce temporary bindings that
1.317 + are visible to the given debuggee code and which refer to debugger-held
1.318 + debuggee values, and do so without mutating any existing debuggee
1.319 + environment.
1.320 +
1.321 + Note that, like `eval`, declarations in the <i>code</i> passed to
1.322 + `evalWithBindings` affect the environment of this frame, even as that
1.323 + environment is extended by bindings visible within <i>code</i>. (In the
1.324 + terms used by the ECMAScript specification, the `VariableEnvironment`
1.325 + of the execution context for the eval code is the `VariableEnvironment`
1.326 + of the execution context that this frame represents, and the
1.327 + <i>bindings</i> appear in a new declarative environment, which is the
1.328 + eval code's `LexicalEnvironment`.) If implementation restrictions
1.329 + prevent SpiderMonkey from extending this frame's environment as
1.330 + requested, this call throws an `Error` exception.
1.331 +
1.332 + The <i>options</i> argument is as for
1.333 + [`Debugger.Frame.prototype.eval`][fr eval], described above.
1.334 +
1.335 +<code>pop(<i>completion</i>)</code> <i>(future plan)</i>
1.336 +: Pop this frame (and any younger frames) from the stack as if this frame
1.337 + had completed as specified by the completion value <i>completion</i>.
1.338 +
1.339 + Note that this does <i>not</i> resume the debuggee's execution; it
1.340 + merely adjusts the debuggee's state to what it would be if this frame's
1.341 + execution had completed. The debuggee will only resume execution when
1.342 + you return from the handler method that brought control to the debugger
1.343 + originally.
1.344 +
1.345 + This cannot remove any `"call"` frames for calls to host functions from
1.346 + the stack. (We might be able to make this work eventually, but it will
1.347 + take some cleverness.)
1.348 +
1.349 +<code>replaceCall(<i>function</i>, <i>this</i>, <i>arguments</i>)</code> <i>(future plan)</i>
1.350 +: Pop any younger frames from the stack, and then change this frame into
1.351 + a frame for a call to <i>function</i>, with the given <i>this</i> value
1.352 + and <i>arguments</i>. <i>This</i> should be a debuggee value, or
1.353 + `{ asConstructor: true }` to invoke <i>function</i> as a constructor,
1.354 + in which case SpiderMonkey provides an appropriate `this` value itself.
1.355 + <i>Arguments</i> should be an array of debuggee values. This frame must
1.356 + be a `"call"` frame.
1.357 +
1.358 + This can be used as a primitive in implementing some forms of a "patch
1.359 + and continue" debugger feature.
1.360 +
1.361 + Note that this does <i>not</i> resume the debuggee's execution; it
1.362 + merely adjusts the debuggee's state to what it would be if this frame
1.363 + were about to make this call. The debuggee will only resume execution
1.364 + when you return from the handler method that brought control to the
1.365 + debugger originally.
1.366 +
1.367 + Like `pop`, this cannot remove `"call"` frames for calls to host
1.368 + functions from the stack.
1.369 +
1.370 +
1.371 +## Generator Frames
1.372 +
1.373 +<i>Not all behavior described in this section has been implemented
1.374 +yet.</i>
1.375 +
1.376 +SpiderMonkey supports generator-iterator objects, which produce a series of
1.377 +values by repeatedly suspending the execution of a function or expression.
1.378 +For example, calling a function that uses `yield` produces a
1.379 +generator-iterator object, as does evaluating a generator expression like
1.380 +`(i*i for each (i in [1,2,3]))`.
1.381 +
1.382 +A generator-iterator object refers to a stack frame with no fixed
1.383 +continuation frame. While the generator's code is running, its continuation
1.384 +is whatever frame called its `next` method; while the generator is
1.385 +suspended, it has no particular continuation frame; and when it resumes
1.386 +again, the continuation frame for that resumption could be different from
1.387 +that of the previous resumption.
1.388 +
1.389 +A `Debugger.Frame` instance representing a generator frame differs from an
1.390 +ordinary stack frame as follows:
1.391 +
1.392 +* A generator frame's `generator` property is true.
1.393 +
1.394 +* A generator frame disappears from the stack each time the generator
1.395 + yields a value and is suspended, and reappears atop the stack when it is
1.396 + resumed to produce the generator's next value. The same `Debugger.Frame`
1.397 + instance refers to the generator frame until it returns, throws an
1.398 + exception, or is terminated.
1.399 +
1.400 +* A generator frame's `older` property refers to the frame's continuation
1.401 + frame while the generator is running, and is `null` while the generator
1.402 + is suspended.
1.403 +
1.404 +* A generator frame's `depth` property reflects the frame's position on
1.405 + the stack when the generator is resumed, and is `null` while the
1.406 + generator is suspended.
1.407 +
1.408 +* A generator frame's `live` property remains true until the frame
1.409 + returns, throws an exception, or is terminated. Thus, generator frames
1.410 + can be live while not present on the stack.
1.411 +
1.412 +The other `Debugger.Frame` methods and accessor properties work as
1.413 +described on generator frames, even when the generator frame is suspended.
1.414 +You may examine a suspended generator frame's variables, and use its
1.415 +`script` and `offset` members to see which `yield` it is suspended at.
1.416 +
1.417 +A `Debugger.Frame` instance referring to a generator-iterator frame has a
1.418 +strong reference to the generator-iterator object; the frame (and its
1.419 +object) will live as long as the `Debugger.Frame` instance does. However,
1.420 +when the generator function returns, throws an exception, or is terminated,
1.421 +thus ending the iteration, the `Debugger.Frame` instance becomes inactive
1.422 +and its `live` property becomes `false`, just as would occur for any other
1.423 +sort of frame that is popped. A non-live `Debugger.Frame` instance no
1.424 +longer holds a strong reference to the generator-iterator object.
