The Tor Browser: js/src/doc/Debugger/Debugger.Object.md@6474c204b198 (annotated)

js/src/doc/Debugger/Debugger.Object.md@6474c204b198 (annotated)

js/src/doc/Debugger/Debugger.Object.md

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 # Debugger.Object
 A `Debugger.Object` instance represents an object in the debuggee,
 providing reflection-oriented methods to inspect and modify its referent.
 The referent's properties do not appear directly as properties of the
 `Debugger.Object` instance; the debugger can access them only through
 methods like `Debugger.Object.prototype.getOwnPropertyDescriptor` and
 `Debugger.Object.prototype.defineProperty`, ensuring that the debugger will
 not inadvertently invoke the referent's getters and setters.
 SpiderMonkey creates exactly one `Debugger.Object` instance for each
 debuggee object it presents to a given [`Debugger`][debugger-object]
 instance: if the debugger encounters the same object through two different
 routes (perhaps two functions are called on the same object), SpiderMonkey
 presents the same `Debugger.Object` instance to the debugger each time.
 This means that the debugger can use the `==` operator to recognize when
 two `Debugger.Object` instances refer to the same debuggee object, and
 place its own properties on a `Debugger.Object` instance to store metadata
 about particular debuggee objects.
 JavaScript code in different compartments can have different views of the
 same object. For example, in Firefox, code in privileged compartments sees
 content DOM element objects without redefinitions or extensions made to
 that object's properties by content code. (In Firefox terminology,
 privileged code sees the element through an "xray wrapper".) To ensure that
 debugger code sees each object just as the debuggee would, each
 `Debugger.Object` instance presents its referent as it would be seen from a
 particular compartment. This "viewing compartment" is chosen to match the
 way the debugger came across the referent. As a consequence, a single
 [`Debugger`][debugger-object] instance may actually have several
 `Debugger.Object` instances: one for each compartment from which the
 referent is viewed.
 If more than one [`Debugger`][debugger-object] instance is debugging the
 same code, each [`Debugger`][debugger-object] gets a separate
 `Debugger.Object` instance for a given object. This allows the code using
 each [`Debugger`][debugger-object] instance to place whatever properties it
 likes on its own `Debugger.Object` instances, without worrying about
 interfering with other debuggers.
 While most `Debugger.Object` instances are created by SpiderMonkey in the
 process of exposing debuggee's behavior and state to the debugger, the
 debugger can use `Debugger.Object.prototype.makeDebuggeeValue` to create
 `Debugger.Object` instances for given debuggee objects, or use
 `Debugger.Object.prototype.copy` and `Debugger.Object.prototype.create` to
 create new objects in debuggee compartments, allocated as if by particular
 debuggee globals.
 `Debugger.Object` instances protect their referents from the garbage
 collector; as long as the `Debugger.Object` instance is live, the referent
 remains live. This means that garbage collection has no visible effect on
 `Debugger.Object` instances.
 ## Accessor Properties of the Debugger.Object prototype
 A `Debugger.Object` instance inherits the following accessor properties
 from its prototype:
 `proto`
 :   The referent's prototype (as a new `Debugger.Object` instance), or
     `null` if it has no prototype.
 `class`
 :   A string naming the ECMAScript `[[Class]]` of the referent.
 `callable`
 :   `true` if the referent is a callable object (such as a function or a
     function proxy); false otherwise.
 `name`
 :   The name of the referent, if it is a named function. If the referent is
     an anonymous function, or not a function at all, this is `undefined`.
     This accessor returns whatever name appeared after the `function`
     keyword in the source code, regardless of whether the function is the
     result of instantiating a function declaration (which binds the
     function to its name in the enclosing scope) or evaluating a function
     expression (which binds the function to its name only within the
     function's body).
 `displayName`
 :   The referent's display name, if the referent is a function with a
     display name. If the referent is not a function, or if it has no display
     name, this is `undefined`.
     If a function has a given name, its display name is the same as its
     given name. In this case, the `displayName` and `name` properties are
     equal.
     If a function has no name, SpiderMonkey attempts to infer an appropriate
     name for it given its context. For example:
         function f() {}          // display name: f (the given name)
         var g = function () {};  // display name: g
         o.p = function () {};    // display name: o.p
         var q = {
           r: function () {}      // display name: q.r
         };
     Note that the display name may not be a proper JavaScript identifier,
     or even a proper expression: we attempt to find helpful names even when
     the function is not immediately assigned as the value of some variable
     or property. Thus, we use <code><i>a</i>/<i>b</i></code> to refer to
     the <i>b</i> defined within <i>a</i>, and <code><i>a</i>&lt;</code> to
     refer to a function that occurs somewhere within an expression that is
     assigned to <i>a</i>. For example:
         function h() {
           var i = function() {};    // display name: h/i
           f(function () {});        // display name: h/<
         }
         var s = f(function () {});  // display name: s<
 `parameterNames`
 :   If the referent is a debuggee function, the names of the its parameters,
     as an array of strings. If the referent is not a debuggee function, or
     not a function at all, this is `undefined`.
     If the referent is a host function for which parameter names are not
     available, return an array with one element per parameter, each of which
     is `undefined`.
     If the referent is a function proxy, return an empty array.
     If the referent uses destructuring parameters, then the array's elements
     reflect the structure of the parameters. For example, if the referent is
     a function declared in this way:
         function f(a, [b, c], {d, e:f}) { ... }
     then this `Debugger.Object` instance's `parameterNames` property would
     have the value:
         ["a", ["b", "c"], {d:"d", e:"f"}]
 `script`
 :   If the referent is a function that is debuggee code, this is that
     function's script, as a [`Debugger.Script`][script] instance. If the
     referent is a function proxy or not debuggee code, this is `undefined`.
 `environment`
 :   If the referent is a function that is debuggee code, a
     [`Debugger.Environment`][environment] instance representing the lexical
     environment enclosing the function when it was created. If the referent
     is a function proxy or not debuggee code, this is `undefined`.
 `proxyHandler`
 :   If the referent is a proxy whose handler object was allocated by
     debuggee code, this is its handler object—the object whose methods are
     invoked to implement accesses of the proxy's properties. If the referent
     is not a proxy whose handler object was allocated by debuggee code, this
     is `null`.
 `proxyCallTrap`
 :   If the referent is a function proxy whose handler object was allocated
     by debuggee code, this is its call trap function—the function called
     when the function proxy is called. If the referent is not a function
     proxy whose handler object was allocated by debuggee code, this is
     `null`.
 `proxyConstructTrap`
 :   If the referent is a function proxy whose handler object was allocated
     by debuggee code, its construction trap function—the function called
     when the function proxy is called via a `new` expression. If the
     referent is not a function proxy whose handler object was allocated by
     debuggee code, this is `null`.
 `global`
 :   A `Debugger.Object` instance referring to the global object in whose
     scope the referent was allocated. This does not unwrap cross-compartment
     wrappers: if the referent is a wrapper, the result refers to the
     wrapper's global, not the wrapped object's global. The result refers to
     the global directly, not via a wrapper.
 `hostAnnotations`
 :   A JavaScript object providing further metadata about the referent, or
     `null` if none is available. The metadata object is in the same
     compartment as this `Debugger.Object` instance. The same metadata
     object is returned each time for a given `Debugger.Object` instance.
     A typical JavaScript embedding provides "host objects" to expose
     application-specific functionality to scripts. The `hostAnnotations`
     accessor consults the embedding for additional information about the
     referent that might be of interest to the debugger. The returned
     object's properties' meanings are up to the embedding. For example, a
     web browser might provide host annotations for global objects to
     distinguish top-level windows, iframes, and internal JavaScript scopes.
     By convention, host annotation objects have a string-valued `"type"`
     property that, taken together with the object's class, indicate what
     sort of thing the referent is. The host annotation object's other
     properties provide further details, as appropriate for the type. For
     example, in Firefox, a metadata object for a JavaScript Module's global
     object might look like this:
         { "type":"jsm", "uri":"resource:://gre/modules/XPCOMUtils.jsm" }
     Firefox provides [DebuggerHostAnnotationsForFirefox annotations] for its
     host objects.
 ## Function Properties of the Debugger.Object prototype
 The functions described below may only be called with a `this` value
 referring to a `Debugger.Object` instance; they may not be used as methods
 of other kinds of objects. The descriptions use "referent" to mean "the
 referent of this `Debugger.Object` instance".
 Unless otherwise specified, these methods are not
 [invocation functions][inv fr]; if a call would cause debuggee code to run
 (say, because it gets or sets an accessor property whose handler is
 debuggee code, or because the referent is a proxy whose traps are debuggee
 code), the call throws a [`Debugger.DebuggeeWouldRun`][wouldrun] exception.
 <code>getProperty(<i>name</i>)</code>
 :   Return the value of the referent's property named <i>name</i>, or
     `undefined` if it has no such property. <i>Name</i> must be a string.
     The result is a debuggee value.
 <code>setProperty(<i>name</i>, <i>value</i>)</code>
 :   Store <i>value</i> as the value of the referent's property named
     <i>name</i>, creating the property if it does not exist. <i>Name</i>
     must be a string; <i>value</i> must be a debuggee value.
 <code>getOwnPropertyDescriptor(<i>name</i>)</code>
 :   Return a property descriptor for the property named <i>name</i> of the
     referent. If the referent has no such property, return `undefined`.
     (This function behaves like the standard
     `Object.getOwnPropertyDescriptor` function, except that the object being
     inspected is implicit; the property descriptor returned is allocated as
     if by code scoped to the debugger's global object (and is thus in the
     debugger's compartment); and its `value`, `get`, and `set` properties,
     if present, are debuggee values.)
 `getOwnPropertyNames()`
 :   Return an array of strings naming all the referent's own properties, as
     if <code>Object.getOwnPropertyNames(<i>referent</i>)</code> had been
     called in the debuggee, and the result copied in the scope of the
     debugger's global object.
 <code>defineProperty(<i>name</i>, <i>attributes</i>)</code>
 :   Define a property on the referent named <i>name</i>, as described by
     the property descriptor <i>descriptor</i>. Any `value`, `get`, and
     `set` properties of <i>attributes</i> must be debuggee values. (This
     function behaves like `Object.defineProperty`, except that the target
     object is implicit, and in a different compartment from the function
     and descriptor.)
 <code>defineProperties(<i>properties</i>)</code>
 :   Add the properties given by <i>properties</i> to the referent. (This
     function behaves like `Object.defineProperties`, except that the target
     object is implicit, and in a different compartment from the
     <i>properties</i> argument.)
 <code>deleteProperty(<i>name</i>)</code>
 :   Remove the referent's property named <i>name</i>. Return true if the
     property was successfully removed, or if the referent has no such
     property. Return false if the property is non-configurable.
 `seal()`
 :   Prevent properties from being added to or deleted from the referent.
     Return this `Debugger.Object` instance. (This function behaves like the
     standard `Object.seal` function, except that the object to be sealed is
     implicit and in a different compartment from the caller.)
 `freeze()`
 :   Prevent properties from being added to or deleted from the referent, and
     mark each property as non-writable. Return this `Debugger.Object`
     instance. (This function behaves like the standard `Object.freeze`
     function, except that the object to be sealed is implicit and in a
     different compartment from the caller.)
 `preventExtensions()`
 :   Prevent properties from being added to the referent. (This function
     behaves like the standard `Object.preventExtensions` function, except
     that the object to operate on is implicit and in a different compartment
     from the caller.)
 `isSealed()`
 :   Return true if the referent is sealed—that is, if it is not extensible,
     and all its properties have been marked as non-configurable. (This
     function behaves like the standard `Object.isSealed` function, except
     that the object inspected is implicit and in a different compartment
     from the caller.)
 `isFrozen()`
 :   Return true if the referent is frozen—that is, if it is not extensible,
     and all its properties have been marked as non-configurable and
     read-only. (This function behaves like the standard `Object.isFrozen`
     function, except that the object inspected is implicit and in a
     different compartment from the caller.)
 `isExtensible()`
 :   Return true if the referent is extensible—that is, if it can have new
     properties defined on it. (This function behaves like the standard
     `Object.isExtensible` function, except that the object inspected is
     implicit and in a different compartment from the caller.)
 <code>copy(<i>value</i>)</code>
 :   Apply the HTML5 "structured cloning" algorithm to create a copy of
     <i>value</i> in the referent's global object (and thus in the referent's
     compartment), and return a `Debugger.Object` instance referring to the
     copy.
     Note that this returns primitive values unchanged. This means you can
     use `Debugger.Object.prototype.copy` as a generic "debugger value to
     debuggee value" conversion function—within the limitations of the
     "structured cloning" algorithm.
 <code>create(<i>prototype</i>, [<i>properties</i>])</code>
 :   Create a new object in the referent's global (and thus in the
     referent's compartment), and return a `Debugger.Object` referring to
     it. The new object's prototype is <i>prototype</i>, which must be an
     `Debugger.Object` instance. The new object's properties are as given by
     <i>properties</i>, as if <i>properties</i> were passed to
     `Debugger.Object.prototype.defineProperties`, with the new
     `Debugger.Object` instance as the `this` value.
 <code>makeDebuggeeValue(<i>value</i>)</code>
 :   Return the debuggee value that represents <i>value</i> in the debuggee.
     If <i>value</i> is a primitive, we return it unchanged; if <i>value</i>
     is an object, we return the `Debugger.Object` instance representing
     that object, wrapped appropriately for use in this `Debugger.Object`'s
     referent's compartment.
     Note that, if <i>value</i> is an object, it need not be one allocated
     in a debuggee global, nor even a debuggee compartment; it can be any
     object the debugger wishes to use as a debuggee value.
     As described above, each `Debugger.Object` instance presents its
     referent as viewed from a particular compartment. Given a
     `Debugger.Object` instance <i>d</i> and an object <i>o</i>, the call
     <code><i>d</i>.makeDebuggeeValue(<i>o</i>)</code> returns a
     `Debugger.Object` instance that presents <i>o</i> as it would be seen
     by code in <i>d</i>'s compartment.
 <code>decompile([<i>pretty</i>])</code>
 :   If the referent is a function that is debuggee code, return the
     JavaScript source code for a function definition equivalent to the
     referent function in its effect and result, as a string. If
     <i>pretty</i> is present and true, produce indented code with line
     breaks. If the referent is not a function that is debuggee code, return
     `undefined`.
 <code>call(<i>this</i>, <i>argument</i>, ...)</code>
 :   If the referent is callable, call it with the given <i>this</i> value
     and <i>argument</i> values, and return a [completion value][cv]
     describing how the call completed. <i>This</i> should be a debuggee
     value, or `{ asConstructor: true }` to invoke the referent as a
     constructor, in which case SpiderMonkey provides an appropriate `this`
     value itself. Each <i>argument</i> must be a debuggee value. All extant
     handler methods, breakpoints, watchpoints, and so on remain active
     during the call. If the referent is not callable, throw a `TypeError`.
     This function follows the [invocation function conventions][inv fr].
 <code>apply(<i>this</i>, <i>arguments</i>)</code>
 :   If the referent is callable, call it with the given <i>this</i> value
     and the argument values in <i>arguments</i>, and return a
     [completion value][cv] describing how the call completed. <i>This</i>
     should be a debuggee value, or `{ asConstructor: true }` to invoke
     <i>function</i> as a constructor, in which case SpiderMonkey provides
     an appropriate `this` value itself. <i>Arguments</i> must either be an
     array (in the debugger) of debuggee values, or `null` or `undefined`,
     which are treated as an empty array. All extant handler methods,
     breakpoints, watchpoints, and so on remain active during the call. If
     the referent is not callable, throw a `TypeError`. This function
     follows the [invocation function conventions][inv fr].
 <code>evalInGlobal(<i>code</i>, [<i>options</i>])</code>
 :   If the referent is a global object, evaluate <i>code</i> in that global
     environment, and return a [completion value][cv] describing how it completed.
     <i>Code</i> is a string. All extant handler methods, breakpoints,
     watchpoints, and so on remain active during the call. This function
     follows the [invocation function conventions][inv fr].
     If the referent is not a global object, throw a `TypeError` exception.
     <i>Code</i> is interpreted as strict mode code when it contains a Use
     Strict Directive.
     If <i>code</i> is not strict mode code, then variable declarations in
     <i>code</i> affect the referent global object. (In the terms used by the
     ECMAScript specification, the `VariableEnvironment` of the execution
     context for the eval code is the referent.)
     The <i>options</i> argument is as for [`Debugger.Frame.prototype.eval`][fr eval].
 <code>evalInGlobalWithBindings(<i>code</i>, <i>bindings</i>, [<i>options</i>])</code>
 :   Like `evalInGlobal`, but evaluate <i>code</i> using the referent as the
     variable object, but with a lexical environment extended with bindings
     from the object <i>bindings</i>. For each own enumerable property of
     <i>bindings</i> named <i>name</i> whose value is <i>value</i>, include a
     variable in the lexical environment in which <i>code</i> is evaluated
     named <i>name</i>, whose value is <i>value</i>. Each <i>value</i> must
     be a debuggee value. (This is not like a `with` statement: <i>code</i>
     may access, assign to, and delete the introduced bindings without having
     any effect on the <i>bindings</i> object.)
     This method allows debugger code to introduce temporary bindings that
     are visible to the given debuggee code and which refer to debugger-held
     debuggee values, and do so without mutating any existing debuggee
     environment.
     Note that, like `evalInGlobal`, if the code passed to
     `evalInGlobalWithBindings` is not strict mode code, then any
     declarations it contains affect the referent global object, even as
     <i>code</i> is evaluated in an environment extended according to
     <i>bindings</i>. (In the terms used by the ECMAScript specification, the
     `VariableEnvironment` of the execution context for non-strict eval code
     is the referent, and the <i>bindings</i> appear in a new declarative
     environment, which is the eval code's `LexicalEnvironment`.)
     The <i>options</i> argument is as for [`Debugger.Frame.prototype.eval`][fr eval].
 `asEnvironment()`
 :   If the referent is a global object, return the [`Debugger.Environment`][environment]
     instance representing the referent as a variable environment for
     evaluating code. If the referent is not a global object, throw a
     `TypeError`.
 <code>setObjectWatchpoint(<i>handler</i>)</code> <i>(future plan)</i>
 :   Set a watchpoint on all the referent's own properties, reporting events
     by calling <i>handler</i>'s methods. Any previous watchpoint handler on
     this `Debugger.Object` instance is replaced. If <i>handler</i> is null,
     the referent is no longer watched. <i>Handler</i> may have the following
     methods, called under the given circumstances:
     <code>add(<i>frame</i>, <i>name</i>, <i>descriptor</i>)</code>
     :   A property named <i>name</i> has been added to the referent.
         <i>Descriptor</i> is a property descriptor of the sort accepted by
         `Debugger.Object.prototype.defineProperty`, giving the newly added
         property's attributes.
     <code>delete(<i>frame</i>, <i>name</i>)</code>
     :   The property named <i>name</i> is about to be deleted from the referent.
     <code>change(<i>frame</i>, <i>name</i>, <i>oldDescriptor</i>, <i>newDescriptor</i>)</code>
     :   The existing property named <i>name</i> on the referent is being changed
         from those given by <i>oldDescriptor</i> to those given by
         <i>newDescriptor</i>. This handler method is only called when attributes
         of the property other than its value are being changed; if only the
         value is changing, SpiderMonkey calls the handler's `set` method.
     <code>set(<i>frame</i>, <i>oldValue</i>, <i>newValue</i>)</code>
     :   The data property named <i>name</i> of the referent is about to have its
         value changed from <i>oldValue</i> to <i>newValue</i>.
         SpiderMonkey only calls this method on assignments to data properties
         that will succeed; assignments to un-writable data properties fail
         without notifying the debugger.
     <code>extensionsPrevented(<i>frame</i>)</code>
     :   The referent has been made non-extensible, as if by a call to
         `Object.preventExtensions`.
     For all watchpoint handler methods:
     * Handler calls receive the handler object itself as the `this` value.
     * The <i>frame</i> argument is the current stack frame, whose code is
       about to perform the operation on the object being reported.
     * If the method returns `undefined`, then SpiderMonkey makes the announced
       change to the object, and continues execution normally. If the method
       returns an object:
     * If the object has a `superseded` property whose value is a true value,
       then SpiderMonkey does not make the announced change.
     * If the object has a `resume` property, its value is taken as a
       [resumption value][rv], indicating how
       execution should proceed. (However, `return` resumption values are not
       supported.)
     * If a given method is absent from <i>handler</i>, then events of that
       sort are ignored. The watchpoint consults <i>handler</i>'s properties
       each time an event occurs, so adding methods to or removing methods from
       <i>handler</i> after setting the watchpoint enables or disables
       reporting of the corresponding events.
     * Values passed to <i>handler</i>'s methods are debuggee values.
       Descriptors passed to <i>handler</i>'s methods are ordinary objects in
       the debugger's compartment, except for `value`, `get`, and `set`
       properties in descriptors, which are debuggee values; they are the sort
       of value expected by `Debugger.Object.prototype.defineProperty`.
     * Watchpoint handler calls are cross-compartment, intra-thread calls: the
       call takes place in the same thread that changed the property, and in
       <i>handler</i>'s method's compartment (typically the same as the
       debugger's compartment).
     The new watchpoint belongs to the [`Debugger`][debugger-object] instance to which this
     `Debugger.Object` instance belongs; disabling the [`Debugger`][debugger-object] instance
     disables this watchpoint.
 `clearObjectWatchpoint()` <i>(future plan)</i>
 :   Remove any object watchpoint set on the referent.
 <code>setPropertyWatchpoint(<i>name</i>, <i>handler</i>)</code> <i>(future plan)</i>
 :   Set a watchpoint on the referent's property named <i>name</i>, reporting
     events by calling <i>handler</i>'s methods. Any previous watchpoint
     handler on this property for this `Debugger.Object` instance is
     replaced. If <i>handler</i> is null, the property is no longer watched.
     <i>Handler</i> is as described for
     `Debugger.Object.prototype.setObjectWatchpoint`, except that it does not
     receive `extensionsPrevented` events.
 <code>clearPropertyWatchpoint(<i>name</i>)</code> <i>(future plan)</i>
 :   Remove any watchpoint set on the referent's property named <i>name</i>.
 `unwrap()`
 :   If the referent is a wrapper that this `Debugger.Object`'s compartment
     is permitted to unwrap, return a `Debugger.Object` instance referring to
     the wrapped object. If we are not permitted to unwrap the referent,
     return `null`. If the referent is not a wrapper, return this
     `Debugger.Object` instance unchanged.
 `unsafeDereference()`
 :   Return the referent of this `Debugger.Object` instance.
     If the referent is an inner object (say, an HTML5 `Window` object),
     return the corresponding outer object (say, the HTML5 `WindowProxy`
     object). This makes `unsafeDereference` more useful in producing values
     appropriate for direct use by debuggee code, without using [invocation functions][inv fr].
     This method pierces the membrane of `Debugger.Object` instances meant to
     protect debugger code from debuggee code, and allows debugger code to
     access debuggee objects through the standard cross-compartment wrappers,
     rather than via `Debugger.Object`'s reflection-oriented interfaces. This
     method makes it easier to gradually adapt large code bases to this
     Debugger API: adapted portions of the code can use `Debugger.Object`
     instances, but use this method to pass direct object references to code
     that has not yet been updated.

The Tor Browser / annotate

js/src/doc/Debugger/Debugger.Object.md@6474c204b198 (annotated)

js/src/doc/Debugger/Debugger.Object.md