Confirmed users
497
edits
Debugger: Difference between revisions
Jump to navigation
Jump to search
[master d36e9a8] Document Debugger.prototype.makeGlobalObjectReference.
([master 15eb6db] The API and protocol are implemented and deployed.) |
([master d36e9a8] Document Debugger.prototype.makeGlobalObjectReference.) |
||
| Line 3: | Line 3: | ||
The <code>Debugger</code> constructor makes objects with methods for debugging code running in global objects in other compartments. Given a <code>Debugger</code> instance, you can: | The <code>Debugger</code> constructor makes objects with methods for debugging code running in global objects in other compartments. Given a <code>Debugger</code> instance, you can: | ||
<ul> | <ul> | ||
<li>add debuggee global objects to its purview using its <code>addDebuggee</code> method; | <li>add debuggee global objects to its purview using its [[#Debugger.prototype.addDebuggee|<code>addDebuggee</code>]] method; | ||
<li>request notification of basic debugging events like stack frame entry and <code>debugger</code> statement execution by providing appropriate handler functions; | <li>request notification of basic debugging events like stack frame entry and <code>debugger</code> statement execution by providing appropriate handler functions; | ||
<li>set breakpoints in scripts; | <li>set breakpoints in scripts; | ||
| Line 119: | Line 119: | ||
<dl> | <dl> | ||
<dt>new Debugger([<i>global</i>, ...]) | <dt>new Debugger([<i>global</i>, ...]) | ||
<dd>Create a debugger object, and apply its <code>addDebuggee</code> method to each of the given <i>global</i> objects to add them as the initial debuggees. | <dd>Create a debugger object, and apply its [[#Debugger.prototype.addDebuggee|<code>addDebuggee</code>]] method to each of the given <i>global</i> objects to add them as the initial debuggees. | ||
</dl> | </dl> | ||
| Line 224: | Line 224: | ||
<dl> | <dl> | ||
<dt>addDebuggee(<i>global</i>) | <dt>{{anchor|Debugger.prototype.addDebuggee}}addDebuggee(<i>global</i>) | ||
<dd>Add the global object designated by <i>global</i> to the set of global objects this <code>Debugger</code> instance is debugging. If the designated global is already a debuggee, this has no effect. Return this <code>Debugger</code>'s <code>Debugger.Object</code> instance referring to | <dd>Add the global object designated by <i>global</i> to the set of global objects this <code>Debugger</code> instance is debugging. If the designated global is already a debuggee, this has no effect. Return this <code>Debugger</code>'s <code>Debugger.Object</code> instance referring to the designated global. | ||
The value <i>global</i> may be any of the following: | The value <i>global</i> may be any of the following: | ||
| Line 245: | Line 245: | ||
<dd>Remove the global object designated by <i>global</i> from this <code>Debugger</code> instance's set of debuggees. Return <code>undefined</code>. | <dd>Remove the global object designated by <i>global</i> from this <code>Debugger</code> instance's set of debuggees. Return <code>undefined</code>. | ||
This method interprets <i>global</i> using the same rules that <code>addDebuggee</code> does. | This method interprets <i>global</i> using the same rules that [[#Debugger.prototype.addDebuggee|<code>addDebuggee</code>]] does. | ||
<dt>hasDebuggee(<i>global</i>) | <dt>hasDebuggee(<i>global</i>) | ||
<dd>Return <code>true</code> if the global object designated by <i>global</i> is a debuggee of this <code>Debugger</code> instance. | <dd>Return <code>true</code> if the global object designated by <i>global</i> is a debuggee of this <code>Debugger</code> instance. | ||
This method interprets <i>global</i> using the same rules that <code>addDebuggee</code> does. | This method interprets <i>global</i> using the same rules that [[#Debugger.prototype.addDebuggee|<code>addDebuggee</code>]] does. | ||
<dt>getDebuggees() | <dt>getDebuggees() | ||
| Line 306: | Line 306: | ||
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. | 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. | ||
<dt>makeGlobalObjectReference(<i>global</i>) | |||
<dd>Return the <code>Debugger.Object</code> whose referent is the global object designated by <i>global</i>, without adding the designated global as a debuggee. If <i>global</i> does not designate a global object, throw a <code>TypeError</code>. Determine which global is designated by <i>global</i> using the same rules as [[#Debugger.prototype.addDebuggee|<code>Debugger.prototype.addDebuggee</code>]]. | |||
</dl> | </dl> | ||
| Line 865: | Line 868: | ||
<dt>unsafeDereference() | <dt>unsafeDereference() | ||
<dd>Return the referent of this <code>Debugger.Object</code> instance. | <dd>Return the referent of this <code>Debugger.Object</code> instance. | ||
If the referent is an inner object (say, an HTML5 <code>Window</code> object), return the corresponding outer object (say, the HTML5 <code>WindowProxy</code> object). This makes <code>unsafeDereference</code> more useful in producing values appropriate for direct use by debuggee code, without using [[#Invocation_Functions_and_.22debugger.22_Frames|invocation functions]]. | |||
This method pierces the membrane of <code>Debugger.Object</code> 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 <code>Debugger.Object</code>'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 <code>Debugger.Object</code> instances, but use this method to pass direct object references to code that has not yet been updated. | This method pierces the membrane of <code>Debugger.Object</code> 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 <code>Debugger.Object</code>'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 <code>Debugger.Object</code> instances, but use this method to pass direct object references to code that has not yet been updated. | ||