summaryrefslogtreecommitdiffstats
path: root/js/src/doc/Debugger/Debugger.md
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /js/src/doc/Debugger/Debugger.md
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'js/src/doc/Debugger/Debugger.md')
-rw-r--r--js/src/doc/Debugger/Debugger.md496
1 files changed, 496 insertions, 0 deletions
diff --git a/js/src/doc/Debugger/Debugger.md b/js/src/doc/Debugger/Debugger.md
new file mode 100644
index 000000000..ebb75d789
--- /dev/null
+++ b/js/src/doc/Debugger/Debugger.md
@@ -0,0 +1,496 @@
+# The Debugger Object
+
+When called as a constructor, the `Debugger` object creates a new
+`Debugger` instance.
+
+<code>new Debugger([<i>global</i>, ...])</code>
+: Create a debugger object, and apply its [`addDebuggee`][add] method to
+ each of the given <i>global</i> objects to add them as the initial
+ debuggees.
+
+## Accessor Properties of the Debugger Prototype Object
+
+A `Debugger` instance inherits the following accessor properties from
+its prototype:
+
+`enabled`
+: A boolean value indicating whether this `Debugger` instance's handlers,
+ breakpoints, and the like are currently enabled. It is an
+ accessor property with a getter and setter: assigning to it enables or
+ disables this `Debugger` instance; reading it produces true if the
+ instance is enabled, or false otherwise. This property is initially
+ `true` in a freshly created `Debugger` instance.
+
+ This property gives debugger code a single point of control for
+ disentangling itself from the debuggee, regardless of what sort of
+ events or handlers or "points" we add to the interface.
+
+`allowUnobservedAsmJS`
+: A boolean value indicating whether asm.js code running inside this
+ `Debugger` instance's debuggee globals is invisible to Debugger API
+ handlers and breakpoints. Setting this to `false` inhibits the
+ ahead-of-time asm.js compiler and forces asm.js code to run as normal
+ JavaScript. This is an accessor property with a getter and setter. It is
+ initially `false` in a freshly created `Debugger` instance.
+
+ Setting this flag to `true` is intended for uses of subsystems of the
+ Debugger API (e.g, [`Debugger.Source`][source]) for purposes other than
+ step debugging a target JavaScript program.
+
+`collectCoverageInfo`
+: A boolean value indicating whether code coverage should be enabled inside
+ each debuggee of this `Debugger` instance. Changing this flag value will
+ recompile all JIT code to add or remove code coverage
+ instrumentation. Changing this flag when any frame of the debuggee is
+ currently active on the stack will produce an exception.
+
+ Setting this to `true` enables code coverage instrumentation, which can be
+ accessed via the [`Debugger.Script`][script] `getOffsetsCoverage`
+ function. In some cases, the code coverage might expose information which
+ pre-date the modification of this flag. Code coverage reports are monotone,
+ thus one can take a snapshot when the Debugger is enabled, and output the
+ difference.
+
+ Setting this to `false` prevents this `Debugger` instance from requiring any
+ code coverage instrumentation, but it does not guarantee that the
+ instrumentation is not present.
+
+`uncaughtExceptionHook`
+: Either `null` or a function that SpiderMonkey calls when a call to a
+ debug event handler, breakpoint handler, or similar
+ function throws some exception, which we refer to as
+ <i>debugger-exception</i> here. Exceptions thrown in the debugger are
+ not propagated to debuggee code; instead, SpiderMonkey calls this
+ function, passing <i>debugger-exception</i> as its sole argument and
+ the `Debugger` instance as the `this` value. This function should
+ return a [resumption value][rv], which determines how the debuggee
+ should continue.
+
+ If the uncaught exception hook itself throws an exception,
+ <i>uncaught-hook-exception</i>, SpiderMonkey throws a new error object,
+ <i>confess-to-debuggee-exception</i>, to the debuggee whose message
+ blames the debugger, and includes textual descriptions of
+ <i>uncaught-hook-exception</i> and the original
+ <i>debugger-exception</i>.
+
+ If `uncaughtExceptionHook`'s value is `null`, SpiderMonkey throws an
+ exception to the debuggee whose message blames the debugger, and
+ includes a textual description of <i>debugger-exception</i>.
+
+ Assigning anything other than a callable value or `null` to this
+ property throws a `TypeError` exception.
+
+ (This is not an ideal way to handle debugger bugs, but the hope here is
+ that some sort of backstop, even if imperfect, will make life easier for
+ debugger developers. For example, an uncaught exception hook may have
+ access to browser-level features like the `alert` function, which this
+ API's implementation does not, making it possible to present debugger
+ errors to the developer in a way suited to the context.)
+
+
+## Debugger Handler Functions
+
+Each `Debugger` instance inherits accessor properties with which you can
+store handler functions for SpiderMonkey to call when given events occur
+in debuggee code.
+
+When one of the events described below occurs in debuggee code, the engine
+pauses the debuggee and calls the corresponding debugging handler on each
+`Debugger` instance that is observing the debuggee. The handler functions
+receive the `Debugger` instance as their `this` value. Most handler
+functions can return a [resumption value][rv] indicating how the debuggee's
+execution should proceed.
+
+On a new `Debugger` instance, each of these properties is initially
+`undefined`. Any value assigned to a debugging handler must be either a
+function or `undefined`; otherwise a `TypeError` is thrown.
+
+Handler functions run in the same thread in which the event occurred.
+They run in the compartment to which they belong, not in a debuggee
+compartment.
+
+<code>onNewScript(<i>script</i>, <i>global</i>)</code>
+: New code, represented by the [`Debugger.Script`][script] instance
+ <i>script</i>, has been loaded in the scope of the debuggees.
+
+ This method's return value is ignored.
+
+<code>onNewPromise(<i>promise</i>)</code>
+: A new Promise object, referenced by the [`Debugger.Object`][object] instance
+ *promise*, has been allocated in the scope of the debuggees. The Promise's
+ allocation stack can be obtained using the *promiseAllocationStack*
+ accessor property of the [`Debugger.Object`][object] instance *promise*.
+
+ This handler method should return a [resumption value][rv] specifying how
+ the debuggee's execution should proceed. However, note that a <code>{
+ return: <i>value</i> }</code> resumption value is treated like `undefined`
+ ("continue normally"); <i>value</i> is ignored.
+
+<code>onPromiseSettled(<i>promise</i>)</code>
+: A Promise object, referenced by the [`Debugger.Object`][object] instance
+ *promise* that was allocated within a debuggee scope, has settled (either
+ fulfilled or rejected). The Promise's state, fulfillment or rejection
+ value, and the allocation and resolution stacks can be obtained using the
+ Promise-related accessor properties of the [`Debugger.Object`][object]
+ instance *promise*.
+
+ This handler method should return a [resumption value][rv] specifying how
+ the debuggee's execution should proceed. However, note that a <code>{
+ return: <i>value</i> }</code> resumption value is treated like `undefined`
+ ("continue normally"); <i>value</i> is ignored.
+
+<code>onDebuggerStatement(<i>frame</i>)</code>
+: Debuggee code has executed a <i>debugger</i> statement in <i>frame</i>.
+ This method should return a [resumption value][rv] specifying how the
+ debuggee's execution should proceed.
+
+<code>onEnterFrame(<i>frame</i>)</code>
+: The stack frame <i>frame</i> is about to begin executing code.
+ (Naturally, <i>frame</i> is currently the youngest
+ [visible frame][vf].) This method should return
+ a [resumption value][rv] specifying how the debuggee's execution should
+ proceed.
+
+ SpiderMonkey only calls `onEnterFrame` to report
+ [visible][vf], non-`"debugger"` frames.
+
+<code>onExceptionUnwind(<i>frame</i>, <i>value</i>)</code>
+: The exception <i>value</i> has been thrown, and has propagated to
+ <i>frame</i>; <i>frame</i> is the youngest remaining stack frame, and is a
+ debuggee frame. This method should return a [resumption value][rv]
+ specifying how the debuggee's execution should proceed. If it returns
+ `undefined`, the exception continues to propagate as normal: if control in
+ `frame` is in a `try` block, control jumps to the corresponding `catch` or
+ `finally` block; otherwise, <i>frame</i> is popped, and the exception
+ propagates to <i>frame</i>'s caller.
+
+ When an exception's propagation causes control to enter a `finally`
+ block, the exception is temporarily set aside. If the `finally` block
+ finishes normally, the exception resumes propagation, and the debugger's
+ `onExceptionUnwind` handler is called again, in the same frame. (The
+ other possibility is for the `finally` block to exit due to a `return`,
+ `continue`, or `break` statement, or a new exception. In those cases the
+ old exception does not continue to propagate; it is discarded.)
+
+ This handler is not called when unwinding a frame due to an over-recursion
+ or out-of-memory exception.
+
+<code>sourceHandler(<i>ASuffusionOfYellow</i>)</code>
+: This method is never called. If it is ever called, a contradiction has
+ been proven, and the debugger is free to assume that everything is true.
+
+<code>onError(<i>frame</i>, <i>report</i>)</code>
+: SpiderMonkey is about to report an error in <i>frame</i>. <i>Report</i>
+ is an object describing the error, with the following properties:
+
+ `message`
+ : The fully formatted error message.
+
+ `file`
+ : If present, the source file name, URL, etc. (If this property is
+ present, the <i>line</i> property will be too, and vice versa.)
+
+ `line`
+ : If present, the source line number at which the error occurred.
+
+ `lineText`
+ : If present, this is the source code of the offending line.
+
+ `offset`
+ : The index of the character within lineText at which the error occurred.
+
+ `warning`
+ : Present and true if this is a warning; absent otherwise.
+
+ `strict`
+ : Present and true if this error or warning is due to the strict option
+ (not to be confused with ES strict mode)
+
+ `exception`
+ : Present and true if an exception will be thrown; absent otherwise.
+
+ `arguments`
+ : An array of strings, representing the arguments substituted into the
+ error message.
+
+ This method's return value is ignored.
+
+`onNewGlobalObject(global)`
+: A new global object, <i>global</i>, has been created.
+
+ This handler method should return a [resumption value][rv] specifying how
+ the debuggee's execution should proceed. However, note that a <code>{ return:
+ <i>value</i> }</code> resumption value is treated like `undefined` ("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 `Debugger`
+ API observe activity in only those globals that are reachable by the
+ API's user, thus imposing capability-based restrictions on a
+ `Debugger`'s reach. However, the `onNewGlobalObject` 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,
+ `onNewGlobalObject` is only available to privileged code.
+
+
+
+## Function Properties of the Debugger Prototype Object
+
+The functions described below may only be called with a `this` value
+referring to a `Debugger` instance; they may not be used as methods of
+other kinds of objects.
+
+<code id="addDebuggee">addDebuggee(<i>global</i>)</code>
+: Add the global object designated by <i>global</i> to the set of global
+ objects this `Debugger` instance is debugging. If the designated global
+ is already a debuggee, this has no effect. Return this `Debugger`'s
+ [`Debugger.Object`][object] instance referring to the designated global.
+
+ The value <i>global</i> may be any of the following:
+
+ * A global object.
+
+ * An HTML5 `WindowProxy` object (an "outer window", in Firefox
+ terminology), which is treated as if the `Window` object of the
+ browsing context's active document (the "inner window") were passed.
+
+ * A cross-compartment wrapper of an object; we apply the prior rules to
+ the wrapped object.
+
+ * A [`Debugger.Object`][object] instance belonging to this `Debugger` instance;
+ we apply the prior rules to the referent.
+
+ * Any other sort of value is treated as a `TypeError`. (Note that each
+ rule is only applied once in the process of resolving a given
+ <i>global</i> argument. Thus, for example, a [`Debugger.Object`][object]
+ referring to a second [`Debugger.Object`][object] 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 `Debugger` 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 [`Debugger.Object`][object] instance whose referent is
+ the designated global object.
+
+ The `Debugger` 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 `Debugger`'s set of debuggees. (Naturally, the
+ [`Debugger.Object`][object] instance this method returns does hold a strong
+ reference to the added global.)
+
+ If this debugger is [tracking allocation sites][tracking-allocs] and cannot
+ track allocation sites for <i>global</i>, this method throws an `Error`.
+
+`addAllGlobalsAsDebuggees()`
+: This method is like [`addDebuggee`][add], but adds all the global
+ objects from all compartments to this `Debugger` instance's set of
+ debuggees. Note that it skips this debugger's compartment.
+
+ If this debugger is [tracking allocation sites][tracking-allocs] and cannot
+ track allocation sites for some global, this method throws an `Error`.
+ Otherwise this method returns `undefined`.
+
+ This method is only available to debuggers running in privileged
+ code ("chrome", in Firefox). Most functions provided by this `Debugger`
+ API observe activity in only those globals that are reachable by the
+ API's user, thus imposing capability-based restrictions on a
+ `Debugger`'s reach. However, the `addAllGlobalsAsDebuggees` 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, `addAllGlobalsAsDebuggees` is only
+ available to privileged code.
+
+<code>removeDebuggee(<i>global</i>)</code>
+: Remove the global object designated by <i>global</i> from this
+ `Debugger` instance's set of debuggees. Return `undefined`.
+
+ This method interprets <i>global</i> using the same rules that
+ [`addDebuggee`][add] does.
+
+ Removing a global as a debuggee from this `Debugger` clears all breakpoints
+ that belong to that `Debugger` in that global.
+
+`removeAllDebuggees()`
+: Remove all the global objects from this `Debugger` instance's set
+ of debuggees. Return `undefined`.
+
+<code>hasDebuggee(<i>global</i>)</code>
+: Return `true` if the global object designated by <i>global</i> is a
+ debuggee of this `Debugger` instance.
+
+ This method interprets <i>global</i> using the same rules that
+ [`addDebuggee`][add] does.
+
+`getDebuggees()`
+: Return an array of distinct [`Debugger.Object`][object] instances whose referents
+ are all the global objects this `Debugger` instance is debugging.
+
+ Since `Debugger` instances don't hold strong references to their
+ debuggee globals, if a debuggee global is otherwise unreachable, it may
+ be dropped at any moment from the array this method returns.
+
+`getNewestFrame()`
+: Return a [`Debugger.Frame`][frame] instance referring to the youngest
+ [visible frame][vf] currently on the calling thread's stack, or `null`
+ if there are no visible frames on the stack.
+
+<code>findSources([<i>query</i>]) <i>(not yet implemented)</i></code>
+: Return an array of all [`Debugger.Source`][source] instances matching
+ <i>query</i>. Each source appears only once in the array. <i>Query</i>
+ is an object whose properties restrict which sources are returned; a
+ source must meet all the criteria given by <i>query</i> to be returned.
+ If <i>query</i> is omitted, we return all sources of all debuggee
+ scripts.
+
+ <i>Query</i> may have the following properties:
+
+ `url`
+ : The source's `url` property must be equal to this value.
+
+ `global`
+ : The source must have been evaluated in the scope of the given global
+ object. If this property's value is a [`Debugger.Object`][object] instance
+ belonging to this `Debugger` instance, then its referent is used. If the
+ object is not a global object, then the global in whose scope it was
+ allocated is used.
+
+ Note that the result may include sources that can no longer ever be
+ used by the debuggee: say, eval code that has finished running, or
+ source for unreachable functions. Whether such sources appear can be
+ affected by the garbage collector's behavior, so this function's result
+ is not entirely deterministic.
+
+<code>findScripts([<i>query</i>])</code>
+: Return an array of [`Debugger.Script`][script] instances for all debuggee scripts
+ matching <i>query</i>. Each instance appears only once in the array.
+ <i>Query</i> is an object whose properties restrict which scripts are
+ returned; a script must meet all the criteria given by <i>query</i> to
+ be returned. If <i>query</i> is omitted, we return the [`Debugger.Script`][script]
+ instances for all debuggee scripts.
+
+ <i>Query</i> may have the following properties:
+
+ `url`
+ : The script's `url` property must be equal to this value.
+
+ `source`
+ : The script's `source` property must be equal to this value.
+
+ `line`
+ : The script must at least partially cover the given source line. If this
+ property is present, the `url` property must be present as well.
+
+ `column`
+ : The script must include given column on the line given by the `line`
+ property. If this property is present, the `url` and `line` properties
+ must both be present as well.
+
+ `innermost`
+ : If this property is present and true, the script must be the innermost
+ script covering the given source location; scripts of enclosing code are
+ omitted.
+
+ `global`
+ : The script must be in the scope of the given global object. If this
+ property's value is a [`Debugger.Object`][object] instance belonging to this
+ `Debugger` instance, then its referent is used. If the object is not a
+ global object, then the global in whose scope it was allocated is used.
+
+ All properties of <i>query</i> are optional. Passing an empty object
+ returns all debuggee code scripts.
+
+ Note that the result may include [`Debugger.Script`][script] instances for
+ scripts that can no longer ever be used by the debuggee, say, those for
+ eval code that has finished running, or unreachable functions. Whether
+ such scripts appear can be affected by the garbage collector's
+ behavior, so this function's behavior is not entirely deterministic.
+
+<code>findObjects([<i>query</i>])</code>
+: Return an array of [`Debugger.Object`][object] instances referring to each
+ live object allocated in the scope of the debuggee globals that matches
+ *query*. Each instance appears only once in the array. *Query* is an object
+ whose properties restrict which objects are returned; an object must meet
+ all the criteria given by *query* to be returned. If *query* is omitted, we
+ return the [`Debugger.Object`][object] instances for all objects allocated
+ in the scope of debuggee globals.
+
+ The *query* object may have the following properties:
+
+ `class`
+ : If present, only return objects whose internal `[[Class]]`'s name
+ matches the given string. Note that in some cases, the prototype object
+ for a given constructor has the same `[[Class]]` as the instances that
+ refer to it, but cannot itself be used as a valid instance of the
+ class. Code gathering objects by class name may need to examine them
+ further before trying to use them.
+
+ All properties of *query* are optional. Passing an empty object returns all
+ objects in debuggee globals.
+
+ Unlike `findScripts`, this function is deterministic and will never return
+ [`Debugger.Object`s][object] referring to previously unreachable objects
+ that had not been collected yet.
+
+<code>clearBreakpoint(<i>handler</i>)</code>
+: Remove all breakpoints set in this `Debugger` instance that use
+ <i>handler</i> as their handler. Note that, if breakpoints using other
+ handler objects are set at the same location(s) as <i>handler</i>, they
+ remain in place.
+
+`clearAllBreakpoints()`
+: Remove all breakpoints set using this `Debugger` instance.
+
+`findAllGlobals()`
+: Return an array of [`Debugger.Object`][object] instances referring to all the
+ global objects present in this JavaScript instance.
+
+ The results of this call can be affected in non-deterministic ways by
+ the details of the JavaScript implementation. The array may include
+ [`Debugger.Object`][object] 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
+ [`Debugger.Object`][object] 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 `Debugger`
+ API observe activity in only those globals that are reachable by the
+ API's user, thus imposing capability-based restrictions on a
+ `Debugger`'s reach. However, `findAllGlobals` 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, `findAllGlobals` is only
+ available to privileged code.
+
+<code>makeGlobalObjectReference(<i>global</i>)</code>
+: Return the [`Debugger.Object`][object] 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
+ `TypeError`. Determine which global is designated by <i>global</i>
+ using the same rules as [`Debugger.prototype.addDebuggee`][add].
+
+<code>adoptDebuggeeValue(<i>value</i>)</code>
+: Given a debuggee value `value` owned by an arbitrary `Debugger`, return an
+ equivalent debuggee value owned by this `Debugger`.
+
+ If `value` is a primitive value, return it unchanged. If `value` is a
+ `Debugger.Object` owned by an arbitrary `Debugger`, return an equivalent
+ `Debugger.Object` owned by this `Debugger`. Otherwise, if `value` is some
+ other kind of object, and hence not a proper debuggee value, throw a
+ TypeError instead.
+
+## Static methods of the Debugger Object
+
+The functions described below are not called with a `this` value.
+
+<code id="isCompilableUnit">isCompilableUnit(<i>source</i>)</code>
+: Given a string of source code, designated by <i>source</i>, return false if
+ the string might become a valid JavaScript statement with the addition of
+ more lines. Otherwise return true. The intent is to support interactive
+ compilation - accumulate lines in a buffer until isCompilableUnit is true,
+ then pass it to the compiler.