1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/src/doc/Debugger/Conventions.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,163 @@
1.4 +# General Conventions
1.5 +
1.6 +This page describes general conventions used in the [`Debugger`][debugger] API,
1.7 +and defines some terminology used throughout the specification.
1.8 +
1.9 +
1.10 +## Properties
1.11 +
1.12 +Properties of objects that comprise the `Debugger` interface, and those
1.13 +that the interface creates, follow some general conventions:
1.14 +
1.15 +- Instances and prototypes are extensible; you can add your own properties
1.16 + and methods to them.
1.17 +
1.18 +- Properties are configurable. This applies to both "own" and prototype
1.19 + properties, and to both methods and data properties. (Leaving these
1.20 + properties open to redefinition will hopefully make it easier for
1.21 + JavaScript debugger code to cope with bugs, bug fixes, and changes in the
1.22 + interface over time.)
1.23 +
1.24 +- Method properties are writable.
1.25 +
1.26 +- We prefer inherited accessor properties to own data properties. Both are
1.27 + read using the same syntax, but inherited accessors seem like a more
1.28 + accurate reflection of what's going on. Unless otherwise noted, these
1.29 + properties have getters but no setters, as they cannot meaningfully be
1.30 + assigned to.
1.31 +
1.32 +
1.33 +## Debuggee Values
1.34 +
1.35 +The `Debugger` interface follows some conventions to help debuggers safely
1.36 +inspect and modify the debuggee's objects and values. Primitive values are
1.37 +passed freely between debugger and debuggee; copying or wrapping is handled
1.38 +transparently. Objects received from the debuggee (including host objects
1.39 +like DOM elements) are fronted in the debugger by `Debugger.Object`
1.40 +instances, which provide reflection-oriented methods for inspecting their
1.41 +referents; see `Debugger.Object`, below.
1.42 +
1.43 +Of the debugger's objects, only `Debugger.Object` instances may be passed
1.44 +to the debuggee: when this occurs, the debuggee receives the
1.45 +`Debugger.Object`'s referent, not the `Debugger.Object` instance itself.
1.46 +
1.47 +In the descriptions below, the term "debuggee value" means either a
1.48 +primitive value or a `Debugger.Object` instance; it is a value that might
1.49 +be received from the debuggee, or that could be passed to the debuggee.
1.50 +
1.51 +
1.52 +## Debuggee Code
1.53 +
1.54 +Each `Debugger` instance maintains a set of global objects that, taken
1.55 +together, comprise the debuggee. Code evaluated in the scope of a debuggee
1.56 +global object, directly or indirectly, is considered *debuggee code*.
1.57 +Similarly:
1.58 +
1.59 +- a *debuggee frame* is a frame running debuggee code;
1.60 +
1.61 +- a *debuggee function* is a function that closes over a debuggee
1.62 + global object (and thus the function's code is debuggee code);
1.63 +
1.64 +- a *debuggee environment* is an environment whose outermost
1.65 + enclosing environment is a debuggee global object; and
1.66 +
1.67 +- a *debuggee script* is a script containing debuggee code.
1.68 +
1.69 +
1.70 +## Completion Values
1.71 +
1.72 +When a debuggee stack frame completes its execution, or when some sort
1.73 +of debuggee call initiated by the debugger finishes, the `Debugger`
1.74 +interface provides a value describing how the code completed; these are
1.75 +called *completion values*. A completion value has one of the
1.76 +following forms:
1.77 +
1.78 +<code>{ return: <i>value</i> }</code>
1.79 +: The code completed normally, returning <i>value</i>. <i>Value</i> is a
1.80 + debuggee value.
1.81 +
1.82 +<code>{ yield: <i>value</i> }</code>
1.83 +: <i>(Not yet implemented.)</i> The running code is a generator frame
1.84 + which has yielded <i>value</i>. <i>Value</i> is a debuggee value.
1.85 +
1.86 +<code>{ throw: <i>value</i> }</code>
1.87 +: The code threw <i>value</i> as an exception. <i>Value</i> is a debuggee
1.88 + value.
1.89 +
1.90 +`null`
1.91 +: The code was terminated, as if by the "slow script" dialog box.
1.92 +
1.93 +If control reaches the end of a generator frame, the completion value is
1.94 +<code>{ throw: <i>stop</i> }</code> where <i>stop</i> is a
1.95 +`Debugger.Object` object representing the `StopIteration` object being
1.96 +thrown.
1.97 +
1.98 +
1.99 +## Resumption Values
1.100 +
1.101 +As the debuggee runs, the `Debugger` interface calls various
1.102 +debugger-provided handler functions to report the debuggee's behavior.
1.103 +Some of these calls can return a value indicating how the debuggee's
1.104 +execution should continue; these are called *resumption values*. A
1.105 +resumption value has one of the following forms:
1.106 +
1.107 +`undefined`
1.108 +: The debuggee should continue execution normally.
1.109 +
1.110 +<code>{ return: <i>value</i> }</code>
1.111 +: Return <i>value</i> immediately as the current value of the function.
1.112 + <i>Value</i> must be a debuggee value. (Most handler functions support
1.113 + this, except those whose descriptions say otherwise.) If the function
1.114 + was called as a constructor (that is, via a `new` expression), then
1.115 + <i>value</i> serves as the value returned by the function's body, not
1.116 + that produced by the `new` expression: if the value is not an object,
1.117 + the `new` expression returns the frame's `this` value.
1.118 +
1.119 +<code>{ yield: <i>value</i> }</code>
1.120 +: <i>(Not yet implemented.)</i> Yield <i>value</i> immediately as the
1.121 + next value of the current frame, which must be a generator frame.
1.122 + <i>Value</i> is a debuggee value. The current frame must be a generator
1.123 + frame that has not yet completed in some other way. You may use `yield`
1.124 + resumption values to substitute a new value or one already yielded by a
1.125 + generator, or to make a generator yield additional values.
1.126 +
1.127 +<code>{ throw: <i>value</i> }</code>
1.128 +: Throw <i>value</i> as an exception from the current bytecode
1.129 + instruction. <i>Value</i> must be a debuggee value.
1.130 +
1.131 +`null`
1.132 +: Terminate the debuggee, as if it had been cancelled by the "slow script"
1.133 + dialog box.
1.134 +
1.135 +If a function that would normally return a resumption value to indicate
1.136 +how the debuggee should continue instead throws an exception, we never
1.137 +propagate such an exception to the debuggee; instead, we call the
1.138 +associated `Debugger` instance's `uncaughtExceptionHook` property, as
1.139 +described below.
1.140 +
1.141 +
1.142 +## The `Debugger.DebuggeeWouldRun` Exception
1.143 +
1.144 +Some debugger operations that appear to simply inspect the debuggee's state
1.145 +may actually cause debuggee code to run. For example, reading a variable
1.146 +might run a getter function on the global or on a `with` expression's
1.147 +operand; and getting an object's property descriptor will run a handler
1.148 +trap if the object is a proxy. To protect the debugger's integrity, only
1.149 +methods whose stated purpose is to run debuggee code can do so. These
1.150 +methods are called [invocation functions][inv fr], and they follow certain
1.151 +common conventions to report the debuggee's behavior safely. For other
1.152 +methods, if their normal operation would cause debuggee code to run, they
1.153 +throw an instance of the `Debugger.DebuggeeWouldRun` exception.
1.154 +
1.155 +A `Debugger.DebuggeeWouldRun` exception may have a `cause` property,
1.156 +providing more detailed information on why the debuggee would have run. The
1.157 +`cause` property's value is one of the following strings:
1.158 +
1.159 + <i>cause</i> value meaning
1.160 + -------------------- --------------------------------------------------------------------------------
1.161 + "proxy" Carrying out the operation would have caused a proxy handler to run.
1.162 + "getter" Carrying out the operation would have caused an object property getter to run.
1.163 + "setter" Carrying out the operation would have caused an object property setter to run.
1.164 +
1.165 +If the system can't determine why control attempted to enter the debuggee,
1.166 +it will leave the exception's `cause` property undefined.
