graal-compiler: graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java comparison

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java @ 20893:263ab98b3bf0

Truffle/Instrumentation: rename ASTInstrumentListener to StandardInstrumentListener

author	Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date	Fri, 10 Apr 2015 21:14:14 -0700
parents	73b1844b5b14
children	129a09815063

comparison

equal deleted inserted replaced

-:73b1844b5b14
+:263ab98b3bf0
 * A dynamically added/removed binding between a {@link Probe}, which provides notification of
 * <em>execution events</em> taking place at a {@link Node} in a Guest Language (GL) Truffle AST,
 * and a <em>listener</em>, which consumes notifications on behalf of an external tool. There are at
 * present two kinds of listeners that be used:
 * <ol>
-* <li>{@link SimpleInstrumentListener} is the simplest and is intended for tools that require no access
+* <li>{@link SimpleInstrumentListener} is the simplest and is intended for tools that require no
-* to the <em>internal execution state</em> of the Truffle execution, only that execution has passed
+* access to the <em>internal execution state</em> of the Truffle execution, only that execution has
-* through a particular location in the program. Information about that location is made available
+* passed through a particular location in the program. Information about that location is made
-* via the {@link Probe} argument in notification methods, including the {@linkplain SourceSection
+* available via the {@link Probe} argument in notification methods, including the
-* source location} of the node and any {@linkplain SyntaxTag tags} that have been applied to the
+* {@linkplain SourceSection source location} of the node and any {@linkplain SyntaxTag tags} that
-* node.</li>
+* have been applied to the node.</li>
-* <li>{@link ASTInstrumentListener} reports the same events and {@link Probe} argument, but
+* <li>{@link StandardInstrumentListener} reports the same events and {@link Probe} argument, but
 * additionally provides access to the execution state via the explicit {@link Node} and
 * {@link Frame} at the current execution site.</li>
 * </ol>
 * <p>
 * <h4>Summary: How to "instrument" an AST location:</h4>
 * <p>
 * <ol>
 * <li>Create an implementation of a <em>listener</em> interface.</li>
 * <li>Create an Instrument via factory methods
 * {@link Instrument#create(SimpleInstrumentListener, String)} or
-* {@link Instrument#create(ASTInstrumentListener, String)}.</li>
+* {@link Instrument#create(StandardInstrumentListener, String)}.</li>
 * <li>"Attach" the Instrument to a Probe via {@link Probe#attach(Instrument)}, at which point event
 * notifications begin to arrive at the listener.</li>
-* <li>When no longer needed, "detach" the Instrument via {@link ASTInstrument#dispose()}, at which
+* <li>When no longer needed, "detach" the Instrument via {@link StandardInstrument#dispose()}, at
-* point event notifications to the listener cease, and the Instrument becomes unusable.</li>
+* which point event notifications to the listener cease, and the Instrument becomes unusable.</li>
 * </ol>
 * <p>
 * <h4>Options for creating listeners:</h4>
 * <p>
 * <ol>
 * <li>Implement one of the <em>listener interfaces</em>: {@link SimpleInstrumentListener} or
-* {@link ASTInstrumentListener} . Their event handling methods account for both the entry into an
+* {@link StandardInstrumentListener} . Their event handling methods account for both the entry into an
 * AST node (about to call) and three possible kinds of <em>execution return</em> from an AST node.</li>
 * <li>Extend one of the <em>helper implementations</em>: {@link DefaultSimpleInstrumentListener} or
-* {@link DefaultASTInstrumentListener}. These provide no-op implementation of every listener
+* {@link DefaultStandardInstrumentListener}. These provide no-op implementation of every listener
 * method, so only the methods of interest need to be overridden.</li>
 * </ol>
 * <p>
-* <h4>General guidelines for {@link ASTInstrumentListener} implementation:</h4>
+* <h4>General guidelines for {@link StandardInstrumentListener} implementation:</h4>
 * <p>
 * Unlike the listener interface {@link SimpleInstrumentListener}, which isolates implementations
-* completely from Truffle internals (and is thus <em>Truffle-safe</em>), implementations of
+* from Truffle internals (and is thus <em>Truffle-safe</em>), implementations of
-* {@link ASTInstrumentListener} can interact directly with (and potentially affect) Truffle
+* {@link StandardInstrumentListener} can interact directly with (and potentially affect) Truffle
 * execution in general and Truffle optimization in particular. For example, it is possible to
 * implement a debugger with this interface.
 * </p>
 * <p>
-* As a consequence, implementations of {@link ASTInstrumentListener} effectively become part of the
+* As a consequence, implementations of {@link StandardInstrumentListener} effectively become part of
-* Truffle execution and must be coded according to general guidelines for Truffle implementations.
+* the Truffle execution and must be coded according to general guidelines for Truffle
-* For example:
+* implementations. For example:
 * <ul>
 * <li>Do not store {@link Frame} or {@link Node} references in fields.</li>
 * <li>Prefer {@code final} fields and (where performance is important) short methods.</li>
 * <li>If needed, pass along the {@link VirtualFrame} reference from an event notification as far as
 * possible through code that is expected to be inlined, since this incurs no runtime overhead. When
 * </ul>
 * <p>
 * <h4>Allowing for AST cloning:</h4>
 * <p>
 * Truffle routinely <em>clones</em> ASTs, which has consequences for implementations of
-* {@link ASTInstrumentListener} (but not for implementations of {@link SimpleInstrumentListener}, from
+* {@link StandardInstrumentListener} (but not for implementations of {@link SimpleInstrumentListener},
-* which cloning is hidden).
+* from which cloning is hidden).
 * <ul>
 * <li>Even though a {@link Probe} is uniquely associated with a particular location in the
 * executing Guest Language program, execution events at that location will in general be
 * implemented by different {@link Node} instances, i.e. <em>clones</em> of the originally probed
 * node.</li>
 * <li>Because of <em>cloning</em> the {@link Node} supplied with notifications to a particular
 * listener will vary, but because they all represent the same GL program location the events should
 * be treated as equivalent for most purposes.</li>
 * </ul>
 * <p>
-* <h4>Access to execution state via {@link ASTInstrumentListener}:</h4>
+* <h4>Access to execution state via {@link StandardInstrumentListener}:</h4>
 * <p>
 * <ul>
 * <li>Notification arguments provide primary access to the GL program's execution states:
 * <ul>
 * <li>{@link Node}: the concrete node (in one of the AST's clones) from which the event originated.
 /**
 * Creates an instrument that will route execution events to a listener, along with access to
 * internal execution state.
 *
-* @param astListener a listener for event generated by the instrument that provides access to
+* @param standardListener a listener for event generated by the instrument that provides access to
 *            internal execution state
 * @param instrumentInfo optional description of the instrument's role, useful for debugging.
 * @return a new instrument, ready for attachment at a probe
 */
-public static Instrument create(ASTInstrumentListener astListener, String instrumentInfo) {
+public static Instrument create(StandardInstrumentListener standardListener, String instrumentInfo) {
-return new ASTInstrument(astListener, instrumentInfo);
+return new StandardInstrument(standardListener, instrumentInfo);
 }
 /**
 * Creates an instrument that, when executed the first time in any particular AST location,
 * invites the tool to provide an AST fragment for attachment/adoption into the running AST.
 * Removes this instrument from an instrument chain.
 */
 abstract AbstractInstrumentNode removeFromChain(AbstractInstrumentNode instrumentNode);
 /**
-* An instrument that propagates events to an instance of {@link ASTInstrumentListener}.
+* An instrument that propagates events to an instance of {@link StandardInstrumentListener}.
 */
-private static final class ASTInstrument extends Instrument {
+private static final class StandardInstrument extends Instrument {
 /**
 * Tool-supplied listener for AST events.
 */
-private final ASTInstrumentListener astListener;
+private final StandardInstrumentListener standardListener;
-private ASTInstrument(ASTInstrumentListener astListener, String instrumentInfo) {
+private StandardInstrument(StandardInstrumentListener standardListener, String instrumentInfo) {
 super(instrumentInfo);
-this.astListener = astListener;
+this.standardListener = standardListener;
 }
 @Override
 AbstractInstrumentNode addToChain(AbstractInstrumentNode nextNode) {
-return new ASTInstrumentNode(nextNode);
+return new StandardInstrumentNode(nextNode);
 }
 @Override
 AbstractInstrumentNode removeFromChain(AbstractInstrumentNode instrumentNode) {
 boolean found = false;
 if (instrumentNode.getInstrument() == this) {
 // Found the match at the head of the chain
 return instrumentNode.nextInstrumentNode;
 }
 // Match not at the head of the chain; remove it.
-found = instrumentNode.removeFromChain(ASTInstrument.this);
+found = instrumentNode.removeFromChain(StandardInstrument.this);
 }
 if (!found) {
 throw new IllegalStateException("Couldn't find instrument node to remove: " + this);
 }
 return instrumentNode;
 }
 @NodeInfo(cost = NodeCost.NONE)
-private final class ASTInstrumentNode extends AbstractInstrumentNode {
+private final class StandardInstrumentNode extends AbstractInstrumentNode {
-private ASTInstrumentNode(AbstractInstrumentNode nextNode) {
+private StandardInstrumentNode(AbstractInstrumentNode nextNode) {
 super(nextNode);
 }
 public void enter(Node node, VirtualFrame vFrame) {
-ASTInstrument.this.astListener.enter(ASTInstrument.this.probe, node, vFrame);
+standardListener.enter(StandardInstrument.this.probe, node, vFrame);
 if (nextInstrumentNode != null) {
 nextInstrumentNode.enter(node, vFrame);
 }
 }
 public void returnVoid(Node node, VirtualFrame vFrame) {
-ASTInstrument.this.astListener.returnVoid(ASTInstrument.this.probe, node, vFrame);
+standardListener.returnVoid(StandardInstrument.this.probe, node, vFrame);
 if (nextInstrumentNode != null) {
 nextInstrumentNode.returnVoid(node, vFrame);
 }
 }
 public void returnValue(Node node, VirtualFrame vFrame, Object result) {
-ASTInstrument.this.astListener.returnValue(ASTInstrument.this.probe, node, vFrame, result);
+standardListener.returnValue(StandardInstrument.this.probe, node, vFrame, result);
 if (nextInstrumentNode != null) {
 nextInstrumentNode.returnValue(node, vFrame, result);
 }
 }
 public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) {
-ASTInstrument.this.astListener.returnExceptional(ASTInstrument.this.probe, node, vFrame, exception);
+standardListener.returnExceptional(StandardInstrument.this.probe, node, vFrame, exception);
 if (nextInstrumentNode != null) {
 nextInstrumentNode.returnExceptional(node, vFrame, exception);
 }
 }
 public String instrumentationInfo() {
 final String info = getInstrumentInfo();
-return info != null ? info : astListener.getClass().getSimpleName();
+return info != null ? info : standardListener.getClass().getSimpleName();
 }
 }
+}
-}
+/**
-/**
+* An instrument that propagates events to an instance of {@link StandardInstrumentListener}.
-* An instrument that propagates events to an instance of {@link ASTInstrumentListener}.
 */
 private static final class ToolNodeInstrument extends Instrument {
 /**
 * Tool-supplied listener for AST events.
 public String instrumentationInfo() {
 final String info = getInstrumentInfo();
 return info != null ? info : toolNodeListener.getClass().getSimpleName();
 }
 }
 }
 public interface TruffleOptListener {
 void notifyIsCompiled(boolean isCompiled);
 }
 public String instrumentationInfo() {
 final String info = getInstrumentInfo();
 return info != null ? info : toolOptListener.getClass().getSimpleName();
 }
 }
 }
 @NodeInfo(cost = NodeCost.NONE)
 abstract class AbstractInstrumentNode extends Node implements TruffleEvents, InstrumentationNode {
 }
 protected String getInstrumentInfo() {
 return Instrument.this.instrumentInfo;
 }
+}
-}
 }

Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java @ 20893:263ab98b3bf0