Confirmed users
497
edits
Debugger: Difference between revisions
Document 'global', 'unwrap', 'onNewGlobal', 'findAllGlobals', 'hostAnnotations', new debuggee designation rules. [master f4bfe86]
(225158d Explain when Debugger.Object instances are not unique per Debugger. Note that environment actors' 'binding' and 'assign' requests can elicit 'threadWouldRun' errors.) |
(Document 'global', 'unwrap', 'onNewGlobal', 'findAllGlobals', 'hostAnnotations', new debuggee designation rules. [master f4bfe86]) |
||
| Line 210: | Line 210: | ||
This method's return value is ignored. | This method's return value is ignored. | ||
<dt>onNewGlobalObject(global) | |||
<dd>A new global object, <i>global</i>, has been created. The application embedding the JavaScript implementation may provide details about what kind of global it is via <code><i>global</i>.hostAnnotations</code>. | |||
This handler method should return a [[#Resumption_Values|resumption value]] specifying how the debuggee's execution should proceed. However, note that a <code>{ return: <i>value</i> }</code> resumption value is treated like <code>undefined</code> ("continue normally"); <i>value</i> is ignored. (Allowing the handler to substitute its own value for the new global object doesn't seem useful.) | |||
This handler method is only available to debuggers running in privileged code ("chrome", in Firefox). Most functions provided by this <code>Debugger</code> API observe activity in only those globals that are reachable by the API's user, thus imposing capability-based restrictions on a <code>Debugger</code>'s reach. However, the <code>onNewGlobalObject</code> method allows the API user to monitor all global object creation that occurs anywhere within the JavaScript system (the "JSRuntime", in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, <code>onNewGlobalObject</code> is only available to privileged code. | |||
</dl> | </dl> | ||
| Line 220: | Line 227: | ||
<dd>Add the global object designated by <i>global</i> to the set of global objects this <code>Debugger</code> instance is debugging. Return this <code>Debugger</code>'s <code>Debugger.Object</code> instance referring to <i>global</i>'s referent. | <dd>Add the global object designated by <i>global</i> to the set of global objects this <code>Debugger</code> instance is debugging. Return this <code>Debugger</code>'s <code>Debugger.Object</code> instance referring to <i>global</i>'s referent. | ||
The value <i>global</i> may be any of the following: | |||
<ul> | <ul> | ||
<li> | <li>A global object. | ||
<li> | <li>An HTML5 <code>WindowProxy</code> object (an "outer window", in Firefox terminology), which is treated as if the <code>Window</code> object of the browsing context's active document (the "inner window") were passed. | ||
<li> | <li>A cross-compartment wrapper of an object; we apply the prior rules to the wrapped object. | ||
<li> | <li>A <code>Debugger.Object</code> instance belonging to this <code>Debugger</code> instance; we apply the prior rules to the referent. | ||
</ul> | </ul> | ||
Any other sort of value is treated as a <code>TypeError</code>. (Note that each rule is only applied once in the process of resolving a given <i>global</i> argument. Thus, for example, a <code>Debugger.Object</code> referring to a second <code>Debugger.Object</code> which refers to a global does not designate that global for the purposes of this function.) | |||
The global designated by <i>global</i> must be in a different compartment than this <code>Debugger</code> instance itself. If adding the designated global's compartment would create a cycle of debugger and debuggee compartments, this method throws an error. | The global designated by <i>global</i> must be in a different compartment than this <code>Debugger</code> instance itself. If adding the designated global's compartment would create a cycle of debugger and debuggee compartments, this method throws an error. | ||
This method returns the <code>Debugger.Object</code> instance whose referent is the designated global object. | |||
The <code>Debugger</code> instance does not hold a strong reference to its debuggee globals: if a debuggee global is not otherwise reachable, then it is dropped from the <code>Debugger</code>'s set of debuggees. | The <code>Debugger</code> instance does not hold a strong reference to its debuggee globals: if a debuggee global is not otherwise reachable, then it is dropped from the <code>Debugger</code>'s set of debuggees. (Naturally, the <code>Debugger.Object</code> instance this method returns does hold a strong reference to the added global.) | ||
<dt>removeDebuggee(<i>global</i>) | <dt>removeDebuggee(<i>global</i>) | ||
| Line 292: | Line 300: | ||
<dd>Clear all watchpoints owned by this <code>Debugger</code> instance. | <dd>Clear all watchpoints owned by this <code>Debugger</code> instance. | ||
<dt>findAllGlobals() | |||
<dd>Return an array of <code>Debugger.Object</code> instances referring to all the global objects present in this JavaScript instance. The application may provide details about what kind of globals they are via the <code>Debugger.Object</code> instances' <code>hostAnnotations</code> accessors. | |||
The results of this call can be affected in non-deterministic ways by the details of the JavaScript implementation. The array may include <code>Debugger.Object</code> instances referring to global objects that are not actually reachable by the debuggee or any other code in the system. (Naturally, once the function has returned, the array's <code>Debugger.Object</code> instances strongly reference the globals they refer to.) | |||
This handler method is only available to debuggers running in privileged code ("chrome", in Firefox). Most functions provided by this <code>Debugger</code> API observe activity in only those globals that are reachable by the API's user, thus imposing capability-based restrictions on a <code>Debugger</code>'s reach. However, <code>findAllGlobals</code> allows the API user to find all global objects anywhere within the JavaScript system (the "JSRuntime", in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, <code>findAllGlobals</code> is only available to privileged code. | |||
</dl> | </dl> | ||
| Line 662: | Line 676: | ||
<dd>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 <code>new</code> expression. If the referent is not a function proxy whose handler object was allocated by debuggee code, this is <code>null</code>. | <dd>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 <code>new</code> expression. If the referent is not a function proxy whose handler object was allocated by debuggee code, this is <code>null</code>. | ||
<dt>global | |||
<dd>A <code>Debugger.Object</code> 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. | |||
<dt>hostAnnotations | |||
<dd>A JavaScript object providing further metadata about the referent, or <code>null</code> if none is available. The metadata object is in the same compartment as this <code>Debugger.Object</code> instance. The same metadata object is returned each time for a given <code>Debugger.Object</code> instance. | |||
A typical JavaScript embedding provides "host objects" to expose application-specific functionality to scripts. The <code>hostAnnotations</code> 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 <code>"type"</code> 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. | |||
</dl> | </dl> | ||
| Line 794: | Line 821: | ||
<dd>Remove any watchpoint set on the referent's property named <i>name</i>. | <dd>Remove any watchpoint set on the referent's property named <i>name</i>. | ||
<dt>unwrap() | |||
<dd>If the referent is a wrapper that this <code>Debugger.Object</code>'s compartment is permitted to unwrap, return a <code>Debugger.Object</code> instance referring to the wrapped object. If we are not permitted to unwrap the referent, return <code>null</code>. If the referent is not a wrapper, return this <code>Debugger.Object</code> instance unchanged. | |||
</dl> | </dl> | ||