Mercurial > hg > graal-compiler
changeset 20908:f166d264af9f
Truflfe/Instrumentaion: migrate client-oriented notes on Probes to a newly written documentation page at https://wiki.openjdk.java.net/display/Graal/Finding+Probes. Replace Probe's Javadoc with implementation notes oriented to implementors.
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Mon, 13 Apr 2015 15:00:57 -0700 |
parents | 06b0a2fb20a1 |
children | f96165ecb6f1 |
files | graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/source/SourceTag.java |
diffstat | 3 files changed, 69 insertions(+), 34 deletions(-) [+] |
line wrap: on
line diff
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Mon Apr 13 11:05:58 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Mon Apr 13 15:00:57 2015 -0700 @@ -30,8 +30,9 @@ import com.oracle.truffle.api.nodes.*; import com.oracle.truffle.api.source.*; -// TODO (mlvdv) move all this to a factory implemented in .impl (together with Probe), -// then break out some of the nested classes into package privates. +// TODO (mlvdv) these statics should not be global. Move them to some kind of context. +// TODO (mlvdv) migrate factory into .impl (together with Probe)? break out nested classes? + /** * A <em>binding</em> between: * <ol> @@ -41,8 +42,8 @@ * </ol> * <p> * Client-oriented documentation for the use of Instruments is available online at <a - * HREF="https://wiki.openjdk.java.net/display/Graal/Listening+for+Execution+Events">Listening for - * Execution Events</a> + * HREF="https://wiki.openjdk.java.net/display/Graal/Listening+for+Execution+Events" + * >https://wiki.openjdk.java.net/display/Graal/Listening+for+Execution+Events</a> * <p> * The implementation of Instruments is complicated by the requirement that Truffle be able to clone * ASTs at any time. In particular, any instrumentation-supporting Nodes that have been attached to @@ -62,29 +63,38 @@ * <ul> * <li>A new Instrument is created in permanent association with a client-provided * <em>listener.</em></li> + * * <li>Multiple Instruments may share a single listener.</li> + * * <li>An Instrument does nothing until it is {@linkplain Probe#attach(Instrument) attached} to a * Probe, at which time the Instrument begins routing execution events from the Probe's AST location * to the Instrument's listener.</li> + * * <li>Neither Instruments nor Probes are {@link Node}s.</li> + * * <li>A Probe has a single source-based location in an AST, but manages a separate * <em>instrumentation chain</em> of Nodes at the equivalent location in each clone of the AST.</li> * <li>When a probed AST is cloned, the instrumentation chain associated with each Probe is cloned * along with the rest of the AST.</li> + * * <li>When a new Instrument (for example an instance of {@link SimpleInstrument} is attached to a * Probe, the Instrument inserts a new instance of its private Node type, * {@link SimpleInstrument.SimpleInstrumentNode}, into <em>each of the instrument chains</em> * managed by the Probe, i.e. one node instance per existing clone of the AST.</li> + * * <li>If an Instrument is attached to a Probe in an AST that subsequently gets cloned, then the * Instrument's private Node type will be cloned along with the rest of the the AST.</li> * <li>Each Instrument's private Node type is a dynamic inner class whose only state is in the * shared (outer) Instrument instance; that state includes a reference to the Instrument's listener. * </li> + * * <li>When an Instrument that has been attached to a Probe is {@linkplain #dispose() disposed}, the * Instrument searches every instrument chain associated with the Probe and removes the instance of * its private Node type.</li> + * * <li>Attaching and disposing an Instrument at a Probe <em>deoptimizes</em> any compilations of the * AST.</li> + * * </ul> * * @see Probe
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java Mon Apr 13 11:05:58 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java Mon Apr 13 15:00:57 2015 -0700 @@ -34,38 +34,62 @@ import com.oracle.truffle.api.source.*; import com.oracle.truffle.api.utilities.*; -//TODO (mlvdv) migrate some of this to external documentation. +//TODO (mlvdv) these statics should not be global. Move them to some kind of context. + /** - * A binding between a particular <em>location</em> in the Truffle AST representation of a running - * Guest Language (GL) program (i.e. a {@link Node}) and a dynamically managed collection of - * "attached" {@linkplain Instrument instrumentation} for use by external tools. The instrumentation - * is intended to persist at the location, even if the specific node instance is - * {@linkplain Node#replace(Node) replaced}. + * A <em>binding</em> between: + * <ol> + * <li>A program location in an executing Truffle AST (defined by a {@link SourceSection}), and</li> + * <li>A dynamically managed collection of "attached" {@linkplain Instrument Instruments} that + * receive event notifications on behalf of external clients.</li> + * </ol> * <p> - * The effect of a binding is to intercept {@linkplain TruffleEvents execution events} arriving at - * the node and notify each attached {@link Instrument} before execution is allowed to proceed to - * the child. + * Client-oriented documentation for the use of Probes is available online at <a + * HREF="https://wiki.openjdk.java.net/display/Graal/Finding+Probes" + * >https://wiki.openjdk.java.net/display/Graal/Finding+Probes</a> * <p> - * A Probe is "inserted" into a GL node via a call to {@link Node#probe()}. No more than one Probe - * can be inserted at a node. + * <h4>Implementation notes:</h4> * <p> - * The "probing" of a Truffle AST must be done after it is complete (i.e. with parent pointers - * correctly assigned), but before any executions. This is done by creating an instance of - * {@link ASTProber} and registering it via {@link #registerASTProber(ASTProber)}, after which it - * will be automatically applied to newly created ASTs. - * <p> - * Each Probe may also have assigned to it any number of {@link SyntaxTag}s, for example identifying - * a node as a {@linkplain StandardSyntaxTag#STATEMENT STATEMENT}. Tags can be queried by tools to - * configure behavior relevant to each probed node. - * <p> - * Instrumentation is implemented by modifying ASTs, both by inserting nodes into each AST at probed - * locations and by attaching additional nodes that implement dynamically attached instruments. - * Attached instrumentation code become, in effect, part of the GL program, and is subject to the - * same levels of optimization as other GL code. This implementation accounts properly for the fact - * that Truffle frequently <em>clones</em> ASTs, along with any attached instrumentation nodes. A - * {@link Probe}, along with attached {@link Instrument}s, represents a <em>logical</em> binding - * with a source code location, producing event notifications that are (mostly) independent of which - * AST clone is executing. + * <ul> + * <li>A Probe must be permanently associated with a <em>program location</em>, defined by a + * particular {@link SourceSection}, even though: + * <ul> + * <li>that location is represented in an AST as a {@link Node}, which might be replaced through + * optimizations such as specialization, and</li> + * <li>Truffle may <em>clone</em> the AST so that the location is actually represented by multiple + * Nodes in multiple ASTs.</li> + * </ul> + * </li> + * + * <li>The effect of the binding is to intercept {@linkplain TruffleEvents execution events} + * arriving at the "probed" AST node and notify each attached {@link Instrument} before execution is + * allowed to proceed to the child and again after execution completes.</li> + * + * <li>A Probe is "inserted" into a GL node via a call to {@link Node#probe()}. No more than one + * Probe can be inserted at a node; a redundant call returns the existing Probe<./li> + * + * <li>The "probing" of a Truffle AST must be done after the AST is complete (i.e. parent pointers + * correctly assigned), but before any cloning or executions. This is done by creating an instance + * of {@link ASTProber} and registering it via {@link #registerASTProber(ASTProber)}, after which it + * will be applied automatically to every newly created AST.</li> + * + * <li>An AST node becomes <em>probed</em> by insertion of a {@link ProbeNode.WrapperNode} into the + * AST, together with an associated {@link ProbeNode} that routes events to all the + * {@linkplain Instrument Instruments} attached to its <em>instrument chain</em>.</li> + * + * <li>When Truffle clones an AST, any attached WrapperNodes and ProbeNodes are cloned as well, + * together with their attached instrument chains. The {@link Probe} instance intercepts cloning + * events and keeps track of all copies.</li> + * + * <li>All attached {@link InstrumentationNode}s effectively become part of the running program: + * <ul> + * <li>Good News: instrumentation code implicitly benefits from every kind of Truffle optimization.</li> + * <li>Bad News: instrumentation code must be implemented carefully to avoid interfering with any + * Truffle optimizations.</li> + * </ul> + * </li> + * + * </ul> * * @see Instrument * @see ASTProber @@ -173,6 +197,7 @@ return taggedProbes; } + // TODO (mlvdv) can this be generalized to permit multiple traps without a performance hit? /** * Sets the current "tag trap"; there can be no more than one set at a time. * <ul>
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/source/SourceTag.java Mon Apr 13 11:05:58 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/source/SourceTag.java Mon Apr 13 15:00:57 2015 -0700 @@ -27,8 +27,8 @@ /** * Categorical information (best implemented as enums} about particular sources of Guest Language * code that can be useful to configure behavior of both the language runtime and external tools. - * These might include {@linkplain Source.Tags standard tags} noting, for example, - * whether the source was read from a file and whether it should be considered library code. + * These might include {@linkplain Source.Tags standard tags} noting, for example, whether the + * source was read from a file and whether it should be considered library code. * <p> * The need for additional tags is likely to arise, in some cases because of issue specific to a * Guest Language, but also for help configuring the behavior of particular tools.