Mercurial > hg > graal-jvmci-8
view graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java @ 19825:907128d02b31
Truffle/Instrumentation: For clients of Instrumentation, replace the TruffleEventListener interface with two: InstrumentListener, and ASTInstrumentListener. The former is simple, completely Truffle-safe (can't affect Truffle execution), and designed for simple tools. The latter is similar to the previous interface.
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Thu, 12 Mar 2015 18:03:05 -0700 |
parents | 10a1fc5e3209 |
children | 2e3cc2a27711 |
line wrap: on
line source
/* * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package com.oracle.truffle.api.instrument; import com.oracle.truffle.api.*; import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary; import com.oracle.truffle.api.frame.*; import com.oracle.truffle.api.instrument.InstrumentationNode.TruffleEvents; import com.oracle.truffle.api.instrument.impl.*; import com.oracle.truffle.api.nodes.*; import com.oracle.truffle.api.source.*; // TODO (mlvdv) migrate some of this to external documentation. // 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. /** * 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 InstrumentListener} 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 * 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(InstrumentListener, String)} or * {@link Instrument#create(ASTInstrumentListener, 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> * </ol> * <p> * <h4>Options for creating listeners:</h4> * <p> * <ol> * <li>Implement one of the <em>listener interfaces</em>: {@link InstrumentListener} or * {@link ASTInstrumentListener} . 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 DefaultInstrumentListener} or * {@link DefaultASTInstrumentListener}. These provide no-op implementation of every listener * method, so only the methods of interest need to be overridden.</li> * <li>Extend one of the <em>helper implementations</em>: {@link SimpleInstrumentListener} or * {@link SimpleASTInstrumentListener}. These re-route all <em>execution returns</em> to a single * method, ignoring return values, so only two methods (for "enter" and "return") will notify all * events.</li> * </ol> * <p> * <h4>General guidelines for {@link ASTInstrumentListener} implementation:</h4> * <p> * Unlike the listener interface {@link InstrumentListener}, 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 * 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: * <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 * access to frame data is needed, substitute a more expensive {@linkplain Frame#materialize() * materialized} representation of the frame.</li> * <li>If a listener calls back to its tool during event handling, and if performance is an issue, * then this should be through a final "callback" field in the instrument, and the called methods * should be minimal.</li> * <li>On the other hand, implementations should prevent Truffle from inlining beyond a reasonable * point with the method annotation {@link TruffleBoundary}.</li> * <li>The implicit "outer" pointer in a non-static inner class is a useful (and * Truffle-optimizable) way to implement callbacks to owner tools.</li> * <li>Primitive-valued return events are boxed for event notification, but Truffle will eliminate * the boxing if they are cast back to their primitive values quickly (in particular before crossing * any {@link TruffleBoundary} annotations). * </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 InstrumentListener}, 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> * <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. * </li> * <li>{@link VirtualFrame}: the current execution frame. * </ul> * <li>Truffle global information is available, for example the execution * {@linkplain TruffleRuntime#iterateFrames(FrameInstanceVisitor) stack}.</li> * <li>Additional API access to execution state may be added in the future.</li> * </ul> * <p> * <h4>Activating and deactivating Instruments:</h4> * <p> * Instruments are <em>single-use</em>: * <ul> * <li>An instrument becomes active only when <em>attached</em> to a Probe via * {@link Probe#attach(Instrument)}, and it may only be attached to a single Probe. It is a runtime * error to attempt attaching a previously attached instrument.</li> * <li>Attaching an instrument modifies every existing clone of the AST to which it is being * attached, which can trigger deoptimization.</li> * <li>The method {@link Instrument#dispose()} makes an instrument inactive by removing it from the * Probe to which it was attached and rendering it permanently inert.</li> * <li>Disposal removes the implementation of an instrument from all ASTs to which it was attached, * which can trigger deoptimization.</li> * </ul> * <p> * <h4>Sharing listeners:</h4> * <p> * Although an Instrument may only be attached to a single Probe, a listener can be shared among * multiple Instruments. This can be useful for observing events that might happen at different * locations in a single AST, for example all assignments to a particular variable. In this case a * new Instrument would be created and attached at each assignment node, but all the Instruments * would be created with the same listener. * <p> * <strong>Disclaimer:</strong> experimental; under development. * * @see Probe * @see TruffleEvents */ public abstract class Instrument { /** * Creates an instrument that will route execution events to a listener. * * @param listener a minimal listener for event generated by the instrument. * @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(InstrumentListener listener, String instrumentInfo) { return new BasicInstrument(listener, instrumentInfo); } /** * 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 * 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); } // TODO (mlvdv) experimental /** * For implementation testing. */ public static Instrument create(TruffleOptListener listener) { return new TruffleOptInstrument(listener, null); } /** * Has this instrument been disposed? stays true once set. */ private boolean isDisposed = false; protected Probe probe = null; /** * Optional documentation, mainly for debugging. */ private final String instrumentInfo; private Instrument(String instrumentInfo) { this.instrumentInfo = instrumentInfo; } /** * Removes this instrument (and any clones) from the probe to which it attached and renders the * instrument inert. * * @throws IllegalStateException if this instrument has already been disposed */ public void dispose() throws IllegalStateException { if (isDisposed) { throw new IllegalStateException("Attempt to dispose an already disposed Instrumennt"); } if (probe != null) { // It's attached probe.disposeInstrument(this); } this.isDisposed = true; } Probe getProbe() { return probe; } void setAttachedTo(Probe probe) { this.probe = probe; } /** * Has this instrument been disposed and rendered unusable? */ boolean isDisposed() { return isDisposed; } abstract AbstractInstrumentNode addToChain(AbstractInstrumentNode nextNode); /** * An instrument that propagates events to an instance of {@link InstrumentListener}. */ private static final class BasicInstrument extends Instrument { /** * Tool-supplied listener for events. */ private final InstrumentListener instrumentListener; private BasicInstrument(InstrumentListener basicListener, String instrumentInfo) { super(instrumentInfo); this.instrumentListener = basicListener; } @Override AbstractInstrumentNode addToChain(AbstractInstrumentNode nextNode) { return new BasicInstrumentNode(nextNode); } @Override AbstractInstrumentNode removeFromChain(AbstractInstrumentNode instrumentNode) { boolean found = false; if (instrumentNode != null) { if (instrumentNode.getInstrument() == this) { // Found the match at the head of the chain return instrumentNode.nextInstrument; } // Match not at the head of the chain; remove it. found = instrumentNode.removeFromChain(BasicInstrument.this); } if (!found) { throw new IllegalStateException("Couldn't find instrument node to remove: " + this); } return instrumentNode; } @NodeInfo(cost = NodeCost.NONE) private final class BasicInstrumentNode extends AbstractInstrumentNode { private BasicInstrumentNode(AbstractInstrumentNode nextNode) { super(nextNode); } public void enter(Node node, VirtualFrame vFrame) { BasicInstrument.this.instrumentListener.enter(BasicInstrument.this.probe); if (nextInstrument != null) { nextInstrument.enter(node, vFrame); } } public void returnVoid(Node node, VirtualFrame vFrame) { BasicInstrument.this.instrumentListener.returnVoid(BasicInstrument.this.probe); if (nextInstrument != null) { nextInstrument.returnVoid(node, vFrame); } } public void returnValue(Node node, VirtualFrame vFrame, Object result) { BasicInstrument.this.instrumentListener.returnValue(BasicInstrument.this.probe, result); if (nextInstrument != null) { nextInstrument.returnValue(node, vFrame, result); } } public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) { BasicInstrument.this.instrumentListener.returnExceptional(BasicInstrument.this.probe, exception); if (nextInstrument != null) { nextInstrument.returnExceptional(node, vFrame, exception); } } public String instrumentationInfo() { final String info = getInstrumentInfo(); return info != null ? info : instrumentListener.getClass().getSimpleName(); } } } /** * Removes this instrument from an instrument chain. */ abstract AbstractInstrumentNode removeFromChain(AbstractInstrumentNode instrumentNode); /** * An instrument that propagates events to an instance of {@link ASTInstrumentListener}. */ private static final class ASTInstrument extends Instrument { /** * Tool-supplied listener for AST events. */ private final ASTInstrumentListener astListener; private ASTInstrument(ASTInstrumentListener astListener, String instrumentInfo) { super(instrumentInfo); this.astListener = astListener; } @Override AbstractInstrumentNode addToChain(AbstractInstrumentNode nextNode) { return new ASTInstrumentNode(nextNode); } @Override AbstractInstrumentNode removeFromChain(AbstractInstrumentNode instrumentNode) { boolean found = false; if (instrumentNode != null) { if (instrumentNode.getInstrument() == this) { // Found the match at the head of the chain return instrumentNode.nextInstrument; } // Match not at the head of the chain; remove it. found = instrumentNode.removeFromChain(ASTInstrument.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 ASTInstrumentNode(AbstractInstrumentNode nextNode) { super(nextNode); } public void enter(Node node, VirtualFrame vFrame) { ASTInstrument.this.astListener.enter(ASTInstrument.this.probe, node, vFrame); if (nextInstrument != null) { nextInstrument.enter(node, vFrame); } } public void returnVoid(Node node, VirtualFrame vFrame) { ASTInstrument.this.astListener.returnVoid(ASTInstrument.this.probe, node, vFrame); if (nextInstrument != null) { nextInstrument.returnVoid(node, vFrame); } } public void returnValue(Node node, VirtualFrame vFrame, Object result) { ASTInstrument.this.astListener.returnValue(ASTInstrument.this.probe, node, vFrame, result); if (nextInstrument != null) { nextInstrument.returnValue(node, vFrame, result); } } public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) { ASTInstrument.this.astListener.returnExceptional(ASTInstrument.this.probe, node, vFrame, exception); if (nextInstrument != null) { nextInstrument.returnExceptional(node, vFrame, exception); } } public String instrumentationInfo() { final String info = getInstrumentInfo(); return info != null ? info : astListener.getClass().getSimpleName(); } } } public interface TruffleOptListener { void notifyIsCompiled(boolean isCompiled); } private static final class TruffleOptInstrument extends Instrument { private final TruffleOptListener toolOptListener; private TruffleOptInstrument(TruffleOptListener listener, String instrumentInfo) { super(instrumentInfo); this.toolOptListener = listener; } @Override AbstractInstrumentNode addToChain(AbstractInstrumentNode nextNode) { return new TruffleOptInstrumentNode(nextNode); } @Override AbstractInstrumentNode removeFromChain(AbstractInstrumentNode instrumentNode) { boolean found = false; if (instrumentNode != null) { if (instrumentNode.getInstrument() == this) { // Found the match at the head of the chain return instrumentNode.nextInstrument; } // Match not at the head of the chain; remove it. found = instrumentNode.removeFromChain(TruffleOptInstrument.this); } if (!found) { throw new IllegalStateException("Couldn't find instrument node to remove: " + this); } return instrumentNode; } @NodeInfo(cost = NodeCost.NONE) private final class TruffleOptInstrumentNode extends AbstractInstrumentNode { private boolean isCompiled; private TruffleOptInstrumentNode(AbstractInstrumentNode nextNode) { super(nextNode); this.isCompiled = CompilerDirectives.inCompiledCode(); } public void enter(Node node, VirtualFrame vFrame) { if (this.isCompiled != CompilerDirectives.inCompiledCode()) { this.isCompiled = CompilerDirectives.inCompiledCode(); TruffleOptInstrument.this.toolOptListener.notifyIsCompiled(this.isCompiled); } if (nextInstrument != null) { nextInstrument.enter(node, vFrame); } } public void returnVoid(Node node, VirtualFrame vFrame) { if (nextInstrument != null) { nextInstrument.returnVoid(node, vFrame); } } public void returnValue(Node node, VirtualFrame vFrame, Object result) { if (nextInstrument != null) { nextInstrument.returnValue(node, vFrame, result); } } public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) { if (nextInstrument != null) { nextInstrument.returnExceptional(node, vFrame, exception); } } 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 { @Child protected AbstractInstrumentNode nextInstrument; protected AbstractInstrumentNode(AbstractInstrumentNode nextNode) { this.nextInstrument = nextNode; } @Override public boolean isInstrumentable() { return false; } /** * Gets the instrument that created this node. */ private Instrument getInstrument() { return Instrument.this; } /** * Removes the node from this chain that was added by a particular instrument, assuming that * the head of the chain is not the one to be replaced. This is awkward, but is required * because {@link Node#replace(Node)} won't take a {@code null} argument. This doesn't work * for the tail of the list, which would be replacing itself with null. So the replacement * must be directed the parent of the node being removed. */ private boolean removeFromChain(Instrument instrument) { assert getInstrument() != instrument; if (nextInstrument == null) { return false; } if (nextInstrument.getInstrument() == instrument) { // Next is the one to remove if (nextInstrument.nextInstrument == null) { // Next is at the tail; just forget nextInstrument = null; } else { // Replace next with its successor nextInstrument.replace(nextInstrument.nextInstrument); } return true; } return nextInstrument.removeFromChain(instrument); } protected String getInstrumentInfo() { return Instrument.this.instrumentInfo; } } }