Mercurial > hg > graal-jvmci-8
diff 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 |
line wrap: on
line diff
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Fri Apr 10 21:00:26 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Fri Apr 10 21:14:14 2015 -0700 @@ -41,13 +41,13 @@ * 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 - * to the <em>internal execution state</em> of the Truffle execution, only that execution has passed - * through a particular location in the program. Information about that location is made available - * via the {@link Probe} argument in notification methods, including the {@linkplain SourceSection - * source location} of the node and any {@linkplain SyntaxTag tags} that have been applied to the - * node.</li> - * <li>{@link ASTInstrumentListener} reports the same events and {@link Probe} argument, but + * <li>{@link SimpleInstrumentListener} is the simplest and is intended for tools that require no + * access to the <em>internal execution state</em> of the Truffle execution, only that execution has + * passed through a particular location in the program. Information about that location is made + * available via the {@link Probe} argument in notification methods, including the + * {@linkplain SourceSection source location} of the node and any {@linkplain SyntaxTag tags} that + * have been applied to the node.</li> + * <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> @@ -58,36 +58,36 @@ * <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 - * point event notifications to the listener cease, and the Instrument becomes unusable.</li> + * <li>When no longer needed, "detach" the Instrument via {@link StandardInstrument#dispose()}, at + * 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 - * {@link ASTInstrumentListener} can interact directly with (and potentially affect) Truffle + * from Truffle internals (and is thus <em>Truffle-safe</em>), implementations of + * {@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 - * Truffle execution and must be coded according to general guidelines for Truffle implementations. - * For example: + * As a consequence, implementations of {@link StandardInstrumentListener} effectively become part of + * the Truffle execution and must be coded according to general guidelines for Truffle + * 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> @@ -110,8 +110,8 @@ * <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 - * which cloning is hidden). + * {@link StandardInstrumentListener} (but not for implementations of {@link SimpleInstrumentListener}, + * 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 @@ -122,7 +122,7 @@ * 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: @@ -181,13 +181,13 @@ * 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) { - return new ASTInstrument(astListener, instrumentInfo); + public static Instrument create(StandardInstrumentListener standardListener, String instrumentInfo) { + return new StandardInstrument(standardListener, instrumentInfo); } /** @@ -346,23 +346,23 @@ 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 @@ -374,7 +374,7 @@ 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); @@ -383,35 +383,35 @@ } @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); } @@ -419,14 +419,13 @@ 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 ASTInstrumentListener}. + * An instrument that propagates events to an instance of {@link StandardInstrumentListener}. */ private static final class ToolNodeInstrument extends Instrument { @@ -520,7 +519,6 @@ return info != null ? info : toolNodeListener.getClass().getSimpleName(); } } - } public interface TruffleOptListener { @@ -601,7 +599,6 @@ return info != null ? info : toolOptListener.getClass().getSimpleName(); } } - } @NodeInfo(cost = NodeCost.NONE) @@ -654,7 +651,5 @@ protected String getInstrumentInfo() { return Instrument.this.instrumentInfo; } - } - }