1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
# General Conventions
This page describes general conventions used in the [`Debugger`][debugger] API,
and defines some terminology used throughout the specification.
## Properties
Properties of objects that comprise the `Debugger` interface, and those
that the interface creates, follow some general conventions:
- Instances and prototypes are extensible; you can add your own properties
and methods to them.
- Properties are configurable. This applies to both "own" and prototype
properties, and to both methods and data properties. (Leaving these
properties open to redefinition will hopefully make it easier for
JavaScript debugger code to cope with bugs, bug fixes, and changes in the
interface over time.)
- Method properties are writable.
- We prefer inherited accessor properties to own data properties. Both are
read using the same syntax, but inherited accessors seem like a more
accurate reflection of what's going on. Unless otherwise noted, these
properties have getters but no setters, as they cannot meaningfully be
assigned to.
## Debuggee Values
The `Debugger` interface follows some conventions to help debuggers safely
inspect and modify the debuggee's objects and values. Primitive values are
passed freely between debugger and debuggee; copying or wrapping is handled
transparently. Objects received from the debuggee (including host objects
like DOM elements) are fronted in the debugger by `Debugger.Object`
instances, which provide reflection-oriented methods for inspecting their
referents; see `Debugger.Object`, below.
Of the debugger's objects, only `Debugger.Object` instances may be passed
to the debuggee: when this occurs, the debuggee receives the
`Debugger.Object`'s referent, not the `Debugger.Object` instance itself.
In the descriptions below, the term "debuggee value" means either a
primitive value or a `Debugger.Object` instance; it is a value that might
be received from the debuggee, or that could be passed to the debuggee.
## Debuggee Code
Each `Debugger` instance maintains a set of global objects that, taken
together, comprise the debuggee. Code evaluated in the scope of a debuggee
global object, directly or indirectly, is considered *debuggee code*.
Similarly:
- a *debuggee frame* is a frame running debuggee code;
- a *debuggee function* is a function that closes over a debuggee
global object (and thus the function's code is debuggee code);
- a *debuggee environment* is an environment whose outermost
enclosing environment is a debuggee global object; and
- a *debuggee script* is a script containing debuggee code.
## Completion Values
When a debuggee stack frame completes its execution, or when some sort
of debuggee call initiated by the debugger finishes, the `Debugger`
interface provides a value describing how the code completed; these are
called *completion values*. A completion value has one of the
following forms:
<code>{ return: <i>value</i> }</code>
: The code completed normally, returning <i>value</i>. <i>Value</i> is a
debuggee value.
<code>{ throw: <i>value</i> }</code>
: The code threw <i>value</i> as an exception. <i>Value</i> is a debuggee
value.
`null`
: The code was terminated, as if by the "slow script" dialog box.
If control reaches the end of a generator frame, the completion value is
<code>{ throw: <i>stop</i> }</code> where <i>stop</i> is a
`Debugger.Object` object representing the `StopIteration` object being
thrown.
## Resumption Values
As the debuggee runs, the `Debugger` interface calls various
debugger-provided handler functions to report the debuggee's behavior.
Some of these calls can return a value indicating how the debuggee's
execution should continue; these are called *resumption values*. A
resumption value has one of the following forms:
`undefined`
: The debuggee should continue execution normally.
<code>{ return: <i>value</i> }</code>
: Return <i>value</i> immediately as the current value of the function.
<i>Value</i> must be a debuggee value. (Most handler functions support
this, except those whose descriptions say otherwise.) If the function
was called as a constructor (that is, via a `new` expression), then
<i>value</i> serves as the value returned by the function's body, not
that produced by the `new` expression: if the value is not an object,
the `new` expression returns the frame's `this` value. Similarly, if
the function is the constructor for a subclass, then a non-object
value may result in a TypeError.
If the frame is a generator or async function, then <i>value</i> must
conform to the iterator protocol: it must be a non-proxy object of the form
<code>{ done: <i>boolean</i>, value: <i>v</i> }</code>, where
both `done` and `value` are ordinary properties.
<code>{ throw: <i>value</i> }</code>
: Throw <i>value</i> as an exception from the current bytecode
instruction. <i>Value</i> must be a debuggee value.
`null`
: Terminate the debuggee, as if it had been cancelled by the "slow script"
dialog box.
If a function that would normally return a resumption value to indicate
how the debuggee should continue instead throws an exception, we never
propagate such an exception to the debuggee; instead, we call the
associated `Debugger` instance's `uncaughtExceptionHook` property, as
described below.
## Timestamps
Timestamps are expressed in units of milliseconds since an arbitrary,
but fixed, epoch. The resolution of timestamps is generally greater
than milliseconds, though no specific resolution is guaranteed.
## The `Debugger.DebuggeeWouldRun` Exception
Some debugger operations that appear to simply inspect the debuggee's state
may actually cause debuggee code to run. For example, reading a variable
might run a getter function on the global or on a `with` expression's
operand; and getting an object's property descriptor will run a handler
trap if the object is a proxy. To protect the debugger's integrity, only
methods whose stated purpose is to run debuggee code can do so. These
methods are called [invocation functions][inv fr], and they follow certain
common conventions to report the debuggee's behavior safely. For other
methods, if their normal operation would cause debuggee code to run, they
throw an instance of the `Debugger.DebuggeeWouldRun` exception.
If there are debugger frames on stack from multiple Debugger instances, the
thrown exception is an instance of the topmost locking debugger's global's
`Debugger.DebuggeeWouldRun`.
A `Debugger.DebuggeeWouldRun` exception may have a `cause` property,
providing more detailed information on why the debuggee would have run. The
`cause` property's value is one of the following strings:
<i>cause</i> value meaning
-------------------- --------------------------------------------------------------------------------
"proxy" Carrying out the operation would have caused a proxy handler to run.
"getter" Carrying out the operation would have caused an object property getter to run.
"setter" Carrying out the operation would have caused an object property setter to run.
If the system can't determine why control attempted to enter the debuggee,
it will leave the exception's `cause` property undefined.
|
