1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/src/doc/Debugger/Debugger.Object.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,534 @@
1.4 +# Debugger.Object
1.5 +
1.6 +A `Debugger.Object` instance represents an object in the debuggee,
1.7 +providing reflection-oriented methods to inspect and modify its referent.
1.8 +The referent's properties do not appear directly as properties of the
1.9 +`Debugger.Object` instance; the debugger can access them only through
1.10 +methods like `Debugger.Object.prototype.getOwnPropertyDescriptor` and
1.11 +`Debugger.Object.prototype.defineProperty`, ensuring that the debugger will
1.12 +not inadvertently invoke the referent's getters and setters.
1.13 +
1.14 +SpiderMonkey creates exactly one `Debugger.Object` instance for each
1.15 +debuggee object it presents to a given [`Debugger`][debugger-object]
1.16 +instance: if the debugger encounters the same object through two different
1.17 +routes (perhaps two functions are called on the same object), SpiderMonkey
1.18 +presents the same `Debugger.Object` instance to the debugger each time.
1.19 +This means that the debugger can use the `==` operator to recognize when
1.20 +two `Debugger.Object` instances refer to the same debuggee object, and
1.21 +place its own properties on a `Debugger.Object` instance to store metadata
1.22 +about particular debuggee objects.
1.23 +
1.24 +JavaScript code in different compartments can have different views of the
1.25 +same object. For example, in Firefox, code in privileged compartments sees
1.26 +content DOM element objects without redefinitions or extensions made to
1.27 +that object's properties by content code. (In Firefox terminology,
1.28 +privileged code sees the element through an "xray wrapper".) To ensure that
1.29 +debugger code sees each object just as the debuggee would, each
1.30 +`Debugger.Object` instance presents its referent as it would be seen from a
1.31 +particular compartment. This "viewing compartment" is chosen to match the
1.32 +way the debugger came across the referent. As a consequence, a single
1.33 +[`Debugger`][debugger-object] instance may actually have several
1.34 +`Debugger.Object` instances: one for each compartment from which the
1.35 +referent is viewed.
1.36 +
1.37 +If more than one [`Debugger`][debugger-object] instance is debugging the
1.38 +same code, each [`Debugger`][debugger-object] gets a separate
1.39 +`Debugger.Object` instance for a given object. This allows the code using
1.40 +each [`Debugger`][debugger-object] instance to place whatever properties it
1.41 +likes on its own `Debugger.Object` instances, without worrying about
1.42 +interfering with other debuggers.
1.43 +
1.44 +While most `Debugger.Object` instances are created by SpiderMonkey in the
1.45 +process of exposing debuggee's behavior and state to the debugger, the
1.46 +debugger can use `Debugger.Object.prototype.makeDebuggeeValue` to create
1.47 +`Debugger.Object` instances for given debuggee objects, or use
1.48 +`Debugger.Object.prototype.copy` and `Debugger.Object.prototype.create` to
1.49 +create new objects in debuggee compartments, allocated as if by particular
1.50 +debuggee globals.
1.51 +
1.52 +`Debugger.Object` instances protect their referents from the garbage
1.53 +collector; as long as the `Debugger.Object` instance is live, the referent
1.54 +remains live. This means that garbage collection has no visible effect on
1.55 +`Debugger.Object` instances.
1.56 +
1.57 +
1.58 +## Accessor Properties of the Debugger.Object prototype
1.59 +
1.60 +A `Debugger.Object` instance inherits the following accessor properties
1.61 +from its prototype:
1.62 +
1.63 +`proto`
1.64 +: The referent's prototype (as a new `Debugger.Object` instance), or
1.65 + `null` if it has no prototype.
1.66 +
1.67 +`class`
1.68 +: A string naming the ECMAScript `[[Class]]` of the referent.
1.69 +
1.70 +`callable`
1.71 +: `true` if the referent is a callable object (such as a function or a
1.72 + function proxy); false otherwise.
1.73 +
1.74 +`name`
1.75 +: The name of the referent, if it is a named function. If the referent is
1.76 + an anonymous function, or not a function at all, this is `undefined`.
1.77 +
1.78 + This accessor returns whatever name appeared after the `function`
1.79 + keyword in the source code, regardless of whether the function is the
1.80 + result of instantiating a function declaration (which binds the
1.81 + function to its name in the enclosing scope) or evaluating a function
1.82 + expression (which binds the function to its name only within the
1.83 + function's body).
1.84 +
1.85 +`displayName`
1.86 +: The referent's display name, if the referent is a function with a
1.87 + display name. If the referent is not a function, or if it has no display
1.88 + name, this is `undefined`.
1.89 +
1.90 + If a function has a given name, its display name is the same as its
1.91 + given name. In this case, the `displayName` and `name` properties are
1.92 + equal.
1.93 +
1.94 + If a function has no name, SpiderMonkey attempts to infer an appropriate
1.95 + name for it given its context. For example:
1.96 +
1.97 + function f() {} // display name: f (the given name)
1.98 + var g = function () {}; // display name: g
1.99 + o.p = function () {}; // display name: o.p
1.100 + var q = {
1.101 + r: function () {} // display name: q.r
1.102 + };
1.103 +
1.104 + Note that the display name may not be a proper JavaScript identifier,
1.105 + or even a proper expression: we attempt to find helpful names even when
1.106 + the function is not immediately assigned as the value of some variable
1.107 + or property. Thus, we use <code><i>a</i>/<i>b</i></code> to refer to
1.108 + the <i>b</i> defined within <i>a</i>, and <code><i>a</i><</code> to
1.109 + refer to a function that occurs somewhere within an expression that is
1.110 + assigned to <i>a</i>. For example:
1.111 +
1.112 + function h() {
1.113 + var i = function() {}; // display name: h/i
1.114 + f(function () {}); // display name: h/<
1.115 + }
1.116 + var s = f(function () {}); // display name: s<
1.117 +
1.118 +`parameterNames`
1.119 +: If the referent is a debuggee function, the names of the its parameters,
1.120 + as an array of strings. If the referent is not a debuggee function, or
1.121 + not a function at all, this is `undefined`.
1.122 +
1.123 + If the referent is a host function for which parameter names are not
1.124 + available, return an array with one element per parameter, each of which
1.125 + is `undefined`.
1.126 +
1.127 + If the referent is a function proxy, return an empty array.
1.128 +
1.129 + If the referent uses destructuring parameters, then the array's elements
1.130 + reflect the structure of the parameters. For example, if the referent is
1.131 + a function declared in this way:
1.132 +
1.133 + function f(a, [b, c], {d, e:f}) { ... }
1.134 +
1.135 + then this `Debugger.Object` instance's `parameterNames` property would
1.136 + have the value:
1.137 +
1.138 + ["a", ["b", "c"], {d:"d", e:"f"}]
1.139 +
1.140 +`script`
1.141 +: If the referent is a function that is debuggee code, this is that
1.142 + function's script, as a [`Debugger.Script`][script] instance. If the
1.143 + referent is a function proxy or not debuggee code, this is `undefined`.
1.144 +
1.145 +`environment`
1.146 +: If the referent is a function that is debuggee code, a
1.147 + [`Debugger.Environment`][environment] instance representing the lexical
1.148 + environment enclosing the function when it was created. If the referent
1.149 + is a function proxy or not debuggee code, this is `undefined`.
1.150 +
1.151 +`proxyHandler`
1.152 +: If the referent is a proxy whose handler object was allocated by
1.153 + debuggee code, this is its handler object—the object whose methods are
1.154 + invoked to implement accesses of the proxy's properties. If the referent
1.155 + is not a proxy whose handler object was allocated by debuggee code, this
1.156 + is `null`.
1.157 +
1.158 +`proxyCallTrap`
1.159 +: If the referent is a function proxy whose handler object was allocated
1.160 + by debuggee code, this is its call trap function—the function called
1.161 + when the function proxy is called. If the referent is not a function
1.162 + proxy whose handler object was allocated by debuggee code, this is
1.163 + `null`.
1.164 +
1.165 +`proxyConstructTrap`
1.166 +: If the referent is a function proxy whose handler object was allocated
1.167 + by debuggee code, its construction trap function—the function called
1.168 + when the function proxy is called via a `new` expression. If the
1.169 + referent is not a function proxy whose handler object was allocated by
1.170 + debuggee code, this is `null`.
1.171 +
1.172 +`global`
1.173 +: A `Debugger.Object` instance referring to the global object in whose
1.174 + scope the referent was allocated. This does not unwrap cross-compartment
1.175 + wrappers: if the referent is a wrapper, the result refers to the
1.176 + wrapper's global, not the wrapped object's global. The result refers to
1.177 + the global directly, not via a wrapper.
1.178 +
1.179 +`hostAnnotations`
1.180 +: A JavaScript object providing further metadata about the referent, or
1.181 + `null` if none is available. The metadata object is in the same
1.182 + compartment as this `Debugger.Object` instance. The same metadata
1.183 + object is returned each time for a given `Debugger.Object` instance.
1.184 +
1.185 + A typical JavaScript embedding provides "host objects" to expose
1.186 + application-specific functionality to scripts. The `hostAnnotations`
1.187 + accessor consults the embedding for additional information about the
1.188 + referent that might be of interest to the debugger. The returned
1.189 + object's properties' meanings are up to the embedding. For example, a
1.190 + web browser might provide host annotations for global objects to
1.191 + distinguish top-level windows, iframes, and internal JavaScript scopes.
1.192 +
1.193 + By convention, host annotation objects have a string-valued `"type"`
1.194 + property that, taken together with the object's class, indicate what
1.195 + sort of thing the referent is. The host annotation object's other
1.196 + properties provide further details, as appropriate for the type. For
1.197 + example, in Firefox, a metadata object for a JavaScript Module's global
1.198 + object might look like this:
1.199 +
1.200 + { "type":"jsm", "uri":"resource:://gre/modules/XPCOMUtils.jsm" }
1.201 +
1.202 + Firefox provides [DebuggerHostAnnotationsForFirefox annotations] for its
1.203 + host objects.
1.204 +
1.205 +
1.206 +
1.207 +## Function Properties of the Debugger.Object prototype
1.208 +
1.209 +The functions described below may only be called with a `this` value
1.210 +referring to a `Debugger.Object` instance; they may not be used as methods
1.211 +of other kinds of objects. The descriptions use "referent" to mean "the
1.212 +referent of this `Debugger.Object` instance".
1.213 +
1.214 +Unless otherwise specified, these methods are not
1.215 +[invocation functions][inv fr]; if a call would cause debuggee code to run
1.216 +(say, because it gets or sets an accessor property whose handler is
1.217 +debuggee code, or because the referent is a proxy whose traps are debuggee
1.218 +code), the call throws a [`Debugger.DebuggeeWouldRun`][wouldrun] exception.
1.219 +
1.220 +<code>getProperty(<i>name</i>)</code>
1.221 +: Return the value of the referent's property named <i>name</i>, or
1.222 + `undefined` if it has no such property. <i>Name</i> must be a string.
1.223 + The result is a debuggee value.
1.224 +
1.225 +<code>setProperty(<i>name</i>, <i>value</i>)</code>
1.226 +: Store <i>value</i> as the value of the referent's property named
1.227 + <i>name</i>, creating the property if it does not exist. <i>Name</i>
1.228 + must be a string; <i>value</i> must be a debuggee value.
1.229 +
1.230 +<code>getOwnPropertyDescriptor(<i>name</i>)</code>
1.231 +: Return a property descriptor for the property named <i>name</i> of the
1.232 + referent. If the referent has no such property, return `undefined`.
1.233 + (This function behaves like the standard
1.234 + `Object.getOwnPropertyDescriptor` function, except that the object being
1.235 + inspected is implicit; the property descriptor returned is allocated as
1.236 + if by code scoped to the debugger's global object (and is thus in the
1.237 + debugger's compartment); and its `value`, `get`, and `set` properties,
1.238 + if present, are debuggee values.)
1.239 +
1.240 +`getOwnPropertyNames()`
1.241 +: Return an array of strings naming all the referent's own properties, as
1.242 + if <code>Object.getOwnPropertyNames(<i>referent</i>)</code> had been
1.243 + called in the debuggee, and the result copied in the scope of the
1.244 + debugger's global object.
1.245 +
1.246 +<code>defineProperty(<i>name</i>, <i>attributes</i>)</code>
1.247 +: Define a property on the referent named <i>name</i>, as described by
1.248 + the property descriptor <i>descriptor</i>. Any `value`, `get`, and
1.249 + `set` properties of <i>attributes</i> must be debuggee values. (This
1.250 + function behaves like `Object.defineProperty`, except that the target
1.251 + object is implicit, and in a different compartment from the function
1.252 + and descriptor.)
1.253 +
1.254 +<code>defineProperties(<i>properties</i>)</code>
1.255 +: Add the properties given by <i>properties</i> to the referent. (This
1.256 + function behaves like `Object.defineProperties`, except that the target
1.257 + object is implicit, and in a different compartment from the
1.258 + <i>properties</i> argument.)
1.259 +
1.260 +<code>deleteProperty(<i>name</i>)</code>
1.261 +: Remove the referent's property named <i>name</i>. Return true if the
1.262 + property was successfully removed, or if the referent has no such
1.263 + property. Return false if the property is non-configurable.
1.264 +
1.265 +`seal()`
1.266 +: Prevent properties from being added to or deleted from the referent.
1.267 + Return this `Debugger.Object` instance. (This function behaves like the
1.268 + standard `Object.seal` function, except that the object to be sealed is
1.269 + implicit and in a different compartment from the caller.)
1.270 +
1.271 +`freeze()`
1.272 +: Prevent properties from being added to or deleted from the referent, and
1.273 + mark each property as non-writable. Return this `Debugger.Object`
1.274 + instance. (This function behaves like the standard `Object.freeze`
1.275 + function, except that the object to be sealed is implicit and in a
1.276 + different compartment from the caller.)
1.277 +
1.278 +`preventExtensions()`
1.279 +: Prevent properties from being added to the referent. (This function
1.280 + behaves like the standard `Object.preventExtensions` function, except
1.281 + that the object to operate on is implicit and in a different compartment
1.282 + from the caller.)
1.283 +
1.284 +`isSealed()`
1.285 +: Return true if the referent is sealed—that is, if it is not extensible,
1.286 + and all its properties have been marked as non-configurable. (This
1.287 + function behaves like the standard `Object.isSealed` function, except
1.288 + that the object inspected is implicit and in a different compartment
1.289 + from the caller.)
1.290 +
1.291 +`isFrozen()`
1.292 +: Return true if the referent is frozen—that is, if it is not extensible,
1.293 + and all its properties have been marked as non-configurable and
1.294 + read-only. (This function behaves like the standard `Object.isFrozen`
1.295 + function, except that the object inspected is implicit and in a
1.296 + different compartment from the caller.)
1.297 +
1.298 +`isExtensible()`
1.299 +: Return true if the referent is extensible—that is, if it can have new
1.300 + properties defined on it. (This function behaves like the standard
1.301 + `Object.isExtensible` function, except that the object inspected is
1.302 + implicit and in a different compartment from the caller.)
1.303 +
1.304 +<code>copy(<i>value</i>)</code>
1.305 +: Apply the HTML5 "structured cloning" algorithm to create a copy of
1.306 + <i>value</i> in the referent's global object (and thus in the referent's
1.307 + compartment), and return a `Debugger.Object` instance referring to the
1.308 + copy.
1.309 +
1.310 + Note that this returns primitive values unchanged. This means you can
1.311 + use `Debugger.Object.prototype.copy` as a generic "debugger value to
1.312 + debuggee value" conversion function—within the limitations of the
1.313 + "structured cloning" algorithm.
1.314 +
1.315 +<code>create(<i>prototype</i>, [<i>properties</i>])</code>
1.316 +: Create a new object in the referent's global (and thus in the
1.317 + referent's compartment), and return a `Debugger.Object` referring to
1.318 + it. The new object's prototype is <i>prototype</i>, which must be an
1.319 + `Debugger.Object` instance. The new object's properties are as given by
1.320 + <i>properties</i>, as if <i>properties</i> were passed to
1.321 + `Debugger.Object.prototype.defineProperties`, with the new
1.322 + `Debugger.Object` instance as the `this` value.
1.323 +
1.324 +<code>makeDebuggeeValue(<i>value</i>)</code>
1.325 +: Return the debuggee value that represents <i>value</i> in the debuggee.
1.326 + If <i>value</i> is a primitive, we return it unchanged; if <i>value</i>
1.327 + is an object, we return the `Debugger.Object` instance representing
1.328 + that object, wrapped appropriately for use in this `Debugger.Object`'s
1.329 + referent's compartment.
1.330 +
1.331 + Note that, if <i>value</i> is an object, it need not be one allocated
1.332 + in a debuggee global, nor even a debuggee compartment; it can be any
1.333 + object the debugger wishes to use as a debuggee value.
1.334 +
1.335 + As described above, each `Debugger.Object` instance presents its
1.336 + referent as viewed from a particular compartment. Given a
1.337 + `Debugger.Object` instance <i>d</i> and an object <i>o</i>, the call
1.338 + <code><i>d</i>.makeDebuggeeValue(<i>o</i>)</code> returns a
1.339 + `Debugger.Object` instance that presents <i>o</i> as it would be seen
1.340 + by code in <i>d</i>'s compartment.
1.341 +
1.342 +<code>decompile([<i>pretty</i>])</code>
1.343 +: If the referent is a function that is debuggee code, return the
1.344 + JavaScript source code for a function definition equivalent to the
1.345 + referent function in its effect and result, as a string. If
1.346 + <i>pretty</i> is present and true, produce indented code with line
1.347 + breaks. If the referent is not a function that is debuggee code, return
1.348 + `undefined`.
1.349 +
1.350 +<code>call(<i>this</i>, <i>argument</i>, ...)</code>
1.351 +: If the referent is callable, call it with the given <i>this</i> value
1.352 + and <i>argument</i> values, and return a [completion value][cv]
1.353 + describing how the call completed. <i>This</i> should be a debuggee
1.354 + value, or `{ asConstructor: true }` to invoke the referent as a
1.355 + constructor, in which case SpiderMonkey provides an appropriate `this`
1.356 + value itself. Each <i>argument</i> must be a debuggee value. All extant
1.357 + handler methods, breakpoints, watchpoints, and so on remain active
1.358 + during the call. If the referent is not callable, throw a `TypeError`.
1.359 + This function follows the [invocation function conventions][inv fr].
1.360 +
1.361 +<code>apply(<i>this</i>, <i>arguments</i>)</code>
1.362 +: If the referent is callable, call it with the given <i>this</i> value
1.363 + and the argument values in <i>arguments</i>, and return a
1.364 + [completion value][cv] describing how the call completed. <i>This</i>
1.365 + should be a debuggee value, or `{ asConstructor: true }` to invoke
1.366 + <i>function</i> as a constructor, in which case SpiderMonkey provides
1.367 + an appropriate `this` value itself. <i>Arguments</i> must either be an
1.368 + array (in the debugger) of debuggee values, or `null` or `undefined`,
1.369 + which are treated as an empty array. All extant handler methods,
1.370 + breakpoints, watchpoints, and so on remain active during the call. If
1.371 + the referent is not callable, throw a `TypeError`. This function
1.372 + follows the [invocation function conventions][inv fr].
1.373 +
1.374 +<code>evalInGlobal(<i>code</i>, [<i>options</i>])</code>
1.375 +: If the referent is a global object, evaluate <i>code</i> in that global
1.376 + environment, and return a [completion value][cv] describing how it completed.
1.377 + <i>Code</i> is a string. All extant handler methods, breakpoints,
1.378 + watchpoints, and so on remain active during the call. This function
1.379 + follows the [invocation function conventions][inv fr].
1.380 + If the referent is not a global object, throw a `TypeError` exception.
1.381 +
1.382 + <i>Code</i> is interpreted as strict mode code when it contains a Use
1.383 + Strict Directive.
1.384 +
1.385 + If <i>code</i> is not strict mode code, then variable declarations in
1.386 + <i>code</i> affect the referent global object. (In the terms used by the
1.387 + ECMAScript specification, the `VariableEnvironment` of the execution
1.388 + context for the eval code is the referent.)
1.389 +
1.390 + The <i>options</i> argument is as for [`Debugger.Frame.prototype.eval`][fr eval].
1.391 +
1.392 +<code>evalInGlobalWithBindings(<i>code</i>, <i>bindings</i>, [<i>options</i>])</code>
1.393 +: Like `evalInGlobal`, but evaluate <i>code</i> using the referent as the
1.394 + variable object, but with a lexical environment extended with bindings
1.395 + from the object <i>bindings</i>. For each own enumerable property of
1.396 + <i>bindings</i> named <i>name</i> whose value is <i>value</i>, include a
1.397 + variable in the lexical environment in which <i>code</i> is evaluated
1.398 + named <i>name</i>, whose value is <i>value</i>. Each <i>value</i> must
1.399 + be a debuggee value. (This is not like a `with` statement: <i>code</i>
1.400 + may access, assign to, and delete the introduced bindings without having
1.401 + any effect on the <i>bindings</i> object.)
1.402 +
1.403 + This method allows debugger code to introduce temporary bindings that
1.404 + are visible to the given debuggee code and which refer to debugger-held
1.405 + debuggee values, and do so without mutating any existing debuggee
1.406 + environment.
1.407 +
1.408 + Note that, like `evalInGlobal`, if the code passed to
1.409 + `evalInGlobalWithBindings` is not strict mode code, then any
1.410 + declarations it contains affect the referent global object, even as
1.411 + <i>code</i> is evaluated in an environment extended according to
1.412 + <i>bindings</i>. (In the terms used by the ECMAScript specification, the
1.413 + `VariableEnvironment` of the execution context for non-strict eval code
1.414 + is the referent, and the <i>bindings</i> appear in a new declarative
1.415 + environment, which is the eval code's `LexicalEnvironment`.)
1.416 +
1.417 + The <i>options</i> argument is as for [`Debugger.Frame.prototype.eval`][fr eval].
1.418 +
1.419 +`asEnvironment()`
1.420 +: If the referent is a global object, return the [`Debugger.Environment`][environment]
1.421 + instance representing the referent as a variable environment for
1.422 + evaluating code. If the referent is not a global object, throw a
1.423 + `TypeError`.
1.424 +
1.425 +<code>setObjectWatchpoint(<i>handler</i>)</code> <i>(future plan)</i>
1.426 +: Set a watchpoint on all the referent's own properties, reporting events
1.427 + by calling <i>handler</i>'s methods. Any previous watchpoint handler on
1.428 + this `Debugger.Object` instance is replaced. If <i>handler</i> is null,
1.429 + the referent is no longer watched. <i>Handler</i> may have the following
1.430 + methods, called under the given circumstances:
1.431 +
1.432 + <code>add(<i>frame</i>, <i>name</i>, <i>descriptor</i>)</code>
1.433 + : A property named <i>name</i> has been added to the referent.
1.434 + <i>Descriptor</i> is a property descriptor of the sort accepted by
1.435 + `Debugger.Object.prototype.defineProperty`, giving the newly added
1.436 + property's attributes.
1.437 +
1.438 + <code>delete(<i>frame</i>, <i>name</i>)</code>
1.439 + : The property named <i>name</i> is about to be deleted from the referent.
1.440 +
1.441 + <code>change(<i>frame</i>, <i>name</i>, <i>oldDescriptor</i>, <i>newDescriptor</i>)</code>
1.442 + : The existing property named <i>name</i> on the referent is being changed
1.443 + from those given by <i>oldDescriptor</i> to those given by
1.444 + <i>newDescriptor</i>. This handler method is only called when attributes
1.445 + of the property other than its value are being changed; if only the
1.446 + value is changing, SpiderMonkey calls the handler's `set` method.
1.447 +
1.448 + <code>set(<i>frame</i>, <i>oldValue</i>, <i>newValue</i>)</code>
1.449 + : The data property named <i>name</i> of the referent is about to have its
1.450 + value changed from <i>oldValue</i> to <i>newValue</i>.
1.451 +
1.452 + SpiderMonkey only calls this method on assignments to data properties
1.453 + that will succeed; assignments to un-writable data properties fail
1.454 + without notifying the debugger.
1.455 +
1.456 + <code>extensionsPrevented(<i>frame</i>)</code>
1.457 + : The referent has been made non-extensible, as if by a call to
1.458 + `Object.preventExtensions`.
1.459 +
1.460 + For all watchpoint handler methods:
1.461 +
1.462 + * Handler calls receive the handler object itself as the `this` value.
1.463 +
1.464 + * The <i>frame</i> argument is the current stack frame, whose code is
1.465 + about to perform the operation on the object being reported.
1.466 +
1.467 + * If the method returns `undefined`, then SpiderMonkey makes the announced
1.468 + change to the object, and continues execution normally. If the method
1.469 + returns an object:
1.470 +
1.471 + * If the object has a `superseded` property whose value is a true value,
1.472 + then SpiderMonkey does not make the announced change.
1.473 +
1.474 + * If the object has a `resume` property, its value is taken as a
1.475 + [resumption value][rv], indicating how
1.476 + execution should proceed. (However, `return` resumption values are not
1.477 + supported.)
1.478 +
1.479 + * If a given method is absent from <i>handler</i>, then events of that
1.480 + sort are ignored. The watchpoint consults <i>handler</i>'s properties
1.481 + each time an event occurs, so adding methods to or removing methods from
1.482 + <i>handler</i> after setting the watchpoint enables or disables
1.483 + reporting of the corresponding events.
1.484 +
1.485 + * Values passed to <i>handler</i>'s methods are debuggee values.
1.486 + Descriptors passed to <i>handler</i>'s methods are ordinary objects in
1.487 + the debugger's compartment, except for `value`, `get`, and `set`
1.488 + properties in descriptors, which are debuggee values; they are the sort
1.489 + of value expected by `Debugger.Object.prototype.defineProperty`.
1.490 +
1.491 + * Watchpoint handler calls are cross-compartment, intra-thread calls: the
1.492 + call takes place in the same thread that changed the property, and in
1.493 + <i>handler</i>'s method's compartment (typically the same as the
1.494 + debugger's compartment).
1.495 +
1.496 + The new watchpoint belongs to the [`Debugger`][debugger-object] instance to which this
1.497 + `Debugger.Object` instance belongs; disabling the [`Debugger`][debugger-object] instance
1.498 + disables this watchpoint.
1.499 +
1.500 +`clearObjectWatchpoint()` <i>(future plan)</i>
1.501 +: Remove any object watchpoint set on the referent.
1.502 +
1.503 +<code>setPropertyWatchpoint(<i>name</i>, <i>handler</i>)</code> <i>(future plan)</i>
1.504 +: Set a watchpoint on the referent's property named <i>name</i>, reporting
1.505 + events by calling <i>handler</i>'s methods. Any previous watchpoint
1.506 + handler on this property for this `Debugger.Object` instance is
1.507 + replaced. If <i>handler</i> is null, the property is no longer watched.
1.508 + <i>Handler</i> is as described for
1.509 + `Debugger.Object.prototype.setObjectWatchpoint`, except that it does not
1.510 + receive `extensionsPrevented` events.
1.511 +
1.512 +<code>clearPropertyWatchpoint(<i>name</i>)</code> <i>(future plan)</i>
1.513 +: Remove any watchpoint set on the referent's property named <i>name</i>.
1.514 +
1.515 +`unwrap()`
1.516 +: If the referent is a wrapper that this `Debugger.Object`'s compartment
1.517 + is permitted to unwrap, return a `Debugger.Object` instance referring to
1.518 + the wrapped object. If we are not permitted to unwrap the referent,
1.519 + return `null`. If the referent is not a wrapper, return this
1.520 + `Debugger.Object` instance unchanged.
1.521 +
1.522 +`unsafeDereference()`
1.523 +: Return the referent of this `Debugger.Object` instance.
1.524 +
1.525 + If the referent is an inner object (say, an HTML5 `Window` object),
1.526 + return the corresponding outer object (say, the HTML5 `WindowProxy`
1.527 + object). This makes `unsafeDereference` more useful in producing values
1.528 + appropriate for direct use by debuggee code, without using [invocation functions][inv fr].
1.529 +
1.530 + This method pierces the membrane of `Debugger.Object` instances meant to
1.531 + protect debugger code from debuggee code, and allows debugger code to
1.532 + access debuggee objects through the standard cross-compartment wrappers,
1.533 + rather than via `Debugger.Object`'s reflection-oriented interfaces. This
1.534 + method makes it easier to gradually adapt large code bases to this
1.535 + Debugger API: adapted portions of the code can use `Debugger.Object`
1.536 + instances, but use this method to pass direct object references to code
1.537 + that has not yet been updated.
