Mercurial > hg > truffle
changeset 22230:3f2052afcb6d
Truffle/Instrumentation: rename the methods in the Instrument listener classes to use the "on" convention, e.g. onEnter(), add Javadoc
line wrap: on
line diff
--- a/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/InstrumentationTest.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/InstrumentationTest.java Sun Sep 20 16:48:50 2015 -0700 @@ -239,19 +239,19 @@ public void attach(Probe probe) { instrument = instrumenter.attach(probe, new SimpleInstrumentListener() { - public void enter(Probe p) { + public void onEnter(Probe p) { enterCount++; } - public void returnVoid(Probe p) { + public void onReturnVoid(Probe p) { leaveCount++; } - public void returnValue(Probe p, Object result) { + public void onReturnValue(Probe p, Object result) { leaveCount++; } - public void returnExceptional(Probe p, Exception exception) { + public void onReturnExceptional(Probe p, Exception exception) { leaveCount++; } @@ -292,19 +292,19 @@ public void attach(Probe probe) { instrument = instrumenter.attach(probe, new StandardInstrumentListener() { - public void enter(Probe p, Node node, VirtualFrame vFrame) { + public void onEnter(Probe p, Node node, VirtualFrame vFrame) { enterCount++; } - public void returnVoid(Probe p, Node node, VirtualFrame vFrame) { + public void onReturnVoid(Probe p, Node node, VirtualFrame vFrame) { leaveCount++; } - public void returnValue(Probe p, Node node, VirtualFrame vFrame, Object result) { + public void onReturnValue(Probe p, Node node, VirtualFrame vFrame, Object result) { leaveCount++; } - public void returnExceptional(Probe p, Node node, VirtualFrame vFrame, Exception exception) { + public void onReturnExceptional(Probe p, Node node, VirtualFrame vFrame, Exception exception) { leaveCount++; } @@ -359,7 +359,7 @@ public int counter = 0; @Override - public void enter(Probe probe) { + public void onEnter(Probe probe) { counter++; } } @@ -372,7 +372,7 @@ public int counter = 0; @Override - public void enter(Probe probe, Node node, VirtualFrame vFrame) { + public void onEnter(Probe probe, Node node, VirtualFrame vFrame) { counter++; } }
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/LineBreakpointFactory.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/LineBreakpointFactory.java Sun Sep 20 16:48:50 2015 -0700 @@ -446,7 +446,7 @@ } } - public void notifyResult(Node node, VirtualFrame vFrame, Object result) { + public void onExecution(Node node, VirtualFrame vFrame, Object result) { final boolean condition = (Boolean) result; if (TRACE) { trace("breakpoint condition = %b %s", condition, getShortDescription()); @@ -456,7 +456,7 @@ } } - public void notifyFailure(Node node, VirtualFrame vFrame, RuntimeException ex) { + public void onFailure(Node node, VirtualFrame vFrame, RuntimeException ex) { addExceptionWarning(ex); if (TRACE) { trace("breakpoint failure = %s %s", ex, getShortDescription()); @@ -483,7 +483,7 @@ private final class UnconditionalLineBreakInstrumentListener extends DefaultStandardInstrumentListener { @Override - public void enter(Probe probe, Node node, VirtualFrame vFrame) { + public void onEnter(Probe probe, Node node, VirtualFrame vFrame) { LineBreakpointImpl.this.nodeEnter(node, vFrame); } }
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/TagBreakpointFactory.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/TagBreakpointFactory.java Sun Sep 20 16:48:50 2015 -0700 @@ -407,7 +407,7 @@ } - public void notifyResult(Node node, VirtualFrame vFrame, Object result) { + public void onExecution(Node node, VirtualFrame vFrame, Object result) { final boolean condition = (Boolean) result; if (TRACE) { trace("breakpoint condition = %b %s", condition, getShortDescription()); @@ -417,7 +417,7 @@ } } - public void notifyFailure(Node node, VirtualFrame vFrame, RuntimeException ex) { + public void onFailure(Node node, VirtualFrame vFrame, RuntimeException ex) { addExceptionWarning(ex); if (TRACE) { trace("breakpoint failure = %s %s", ex, getShortDescription()); @@ -444,7 +444,7 @@ private final class UnconditionalTagBreakInstrumentListener extends DefaultStandardInstrumentListener { @Override - public void enter(Probe probe, Node node, VirtualFrame vFrame) { + public void onEnter(Probe probe, Node node, VirtualFrame vFrame) { TagBreakpointImpl.this.nodeEnter(node, vFrame); } }
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/AdvancedInstrumentResultListener.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/AdvancedInstrumentResultListener.java Sun Sep 20 16:48:50 2015 -0700 @@ -33,6 +33,9 @@ * fragment}, when executed by a * {@linkplain Instrumenter#attach(Probe, AdvancedInstrumentResultListener, AdvancedInstrumentRootFactory, Class, String) * Advanced Instrument}. + * <p> + * Notification is fully synchronous, so overrides have performance implications. Non-trivial + * methods should be coded with Truffle guidelines and cautions in mind. * * @see Instrument * @see AdvancedInstrumentRoot @@ -54,7 +57,7 @@ * @param vFrame execution frame at the guest-language AST node * @param result the result of this AST fragment's execution */ - void notifyResult(Node node, VirtualFrame vFrame, Object result); + void onExecution(Node node, VirtualFrame vFrame, Object result); /** * Notifies listener that execution of client-provided {@linkplain AdvancedInstrumentRoot AST @@ -69,6 +72,6 @@ * @param vFrame execution frame at the guest-language AST node * @param ex the exception */ - void notifyFailure(Node node, VirtualFrame vFrame, RuntimeException ex); + void onFailure(Node node, VirtualFrame vFrame, RuntimeException ex); }
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Sun Sep 20 16:48:50 2015 -0700 @@ -216,7 +216,7 @@ @Override public void enter(Node node, VirtualFrame vFrame) { - SimpleInstrument.this.simpleListener.enter(SimpleInstrument.this.probe); + SimpleInstrument.this.simpleListener.onEnter(SimpleInstrument.this.probe); if (nextInstrumentNode != null) { nextInstrumentNode.enter(node, vFrame); } @@ -224,7 +224,7 @@ @Override public void returnVoid(Node node, VirtualFrame vFrame) { - SimpleInstrument.this.simpleListener.returnVoid(SimpleInstrument.this.probe); + SimpleInstrument.this.simpleListener.onReturnVoid(SimpleInstrument.this.probe); if (nextInstrumentNode != null) { nextInstrumentNode.returnVoid(node, vFrame); } @@ -232,7 +232,7 @@ @Override public void returnValue(Node node, VirtualFrame vFrame, Object result) { - SimpleInstrument.this.simpleListener.returnValue(SimpleInstrument.this.probe, result); + SimpleInstrument.this.simpleListener.onReturnValue(SimpleInstrument.this.probe, result); if (nextInstrumentNode != null) { nextInstrumentNode.returnValue(node, vFrame, result); } @@ -240,7 +240,7 @@ @Override public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) { - SimpleInstrument.this.simpleListener.returnExceptional(SimpleInstrument.this.probe, exception); + SimpleInstrument.this.simpleListener.onReturnExceptional(SimpleInstrument.this.probe, exception); if (nextInstrumentNode != null) { nextInstrumentNode.returnExceptional(node, vFrame, exception); } @@ -303,7 +303,7 @@ @Override public void enter(Node node, VirtualFrame vFrame) { - standardListener.enter(StandardInstrument.this.probe, node, vFrame); + standardListener.onEnter(StandardInstrument.this.probe, node, vFrame); if (nextInstrumentNode != null) { nextInstrumentNode.enter(node, vFrame); } @@ -311,7 +311,7 @@ @Override public void returnVoid(Node node, VirtualFrame vFrame) { - standardListener.returnVoid(StandardInstrument.this.probe, node, vFrame); + standardListener.onReturnVoid(StandardInstrument.this.probe, node, vFrame); if (nextInstrumentNode != null) { nextInstrumentNode.returnVoid(node, vFrame); } @@ -319,7 +319,7 @@ @Override public void returnValue(Node node, VirtualFrame vFrame, Object result) { - standardListener.returnValue(StandardInstrument.this.probe, node, vFrame, result); + standardListener.onReturnValue(StandardInstrument.this.probe, node, vFrame, result); if (nextInstrumentNode != null) { nextInstrumentNode.returnValue(node, vFrame, result); } @@ -327,7 +327,7 @@ @Override public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) { - standardListener.returnExceptional(StandardInstrument.this.probe, node, vFrame, exception); + standardListener.onReturnExceptional(StandardInstrument.this.probe, node, vFrame, exception); if (nextInstrumentNode != null) { nextInstrumentNode.returnExceptional(node, vFrame, exception); } @@ -405,7 +405,7 @@ } } catch (RuntimeException ex) { if (resultListener != null) { - resultListener.notifyFailure(node, vFrame, ex); + resultListener.onFailure(node, vFrame, ex); } } } @@ -414,11 +414,11 @@ final Object result = instrumentRoot.executeRoot(node, vFrame); if (resultListener != null) { checkResultType(result); - resultListener.notifyResult(node, vFrame, result); + resultListener.onExecution(node, vFrame, result); } } catch (RuntimeException ex) { if (resultListener != null) { - resultListener.notifyFailure(node, vFrame, ex); + resultListener.onFailure(node, vFrame, ex); } } }
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrumenter.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrumenter.java Sun Sep 20 16:48:50 2015 -0700 @@ -311,7 +311,7 @@ /** * <em>Attaches</em> a {@link SimpleInstrumentListener listener} to a {@link Probe}, creating a * <em>binding</em> called an {@link Instrument}. Until the Instrument is - * {@linkplain Instrument#dispose() disposed}, it routes notification of + * {@linkplain Instrument#dispose() disposed}, it routes synchronous notification of * {@linkplain EventHandlerNode execution events} taking place at the Probe's AST location to * the listener. * @@ -330,7 +330,7 @@ /** * <em>Attaches</em> a {@link StandardInstrumentListener listener} to a {@link Probe}, creating * a <em>binding</em> called an {@link Instrument}. Until the Instrument is - * {@linkplain Instrument#dispose() disposed}, it routes notification of + * {@linkplain Instrument#dispose() disposed}, it routes synchronous notification of * {@linkplain EventHandlerNode execution events} taking place at the Probe's AST location to * the listener. * @@ -349,7 +349,7 @@ /** * <em>Attaches</em> a {@link AdvancedInstrumentResultListener listener} to a {@link Probe}, * creating a <em>binding</em> called an {@link Instrument}. Until the Instrument is - * {@linkplain Instrument#dispose() disposed}, it routes notification of + * {@linkplain Instrument#dispose() disposed}, it routes synchronous notification of * {@linkplain EventHandlerNode execution events} taking place at the Probe's AST location to * the listener. * <p>
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SimpleInstrumentListener.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SimpleInstrumentListener.java Sun Sep 20 16:48:50 2015 -0700 @@ -27,7 +27,7 @@ import com.oracle.truffle.api.source.SourceSection; /** - * A receiver of Truffle execution events that can act on behalf of an external client. + * A receiver of Truffle AST execution events that can act on behalf of an external client. * <p> * The {@link Probe} instance provides access to the {@link SourceSection} associated with the * event, as well as any {@link SyntaxTag}s that have been applied at that program's location. @@ -39,6 +39,9 @@ * Clients are free, of course, to record additional information in the listener implementation that * carries additional information about the context and reason for the particular {@link Instrument} * that is to be created from the listener. + * <p> + * Notification is fully synchronous, so overrides have performance implications. Non-trivial + * methods should be coded with Truffle guidelines and cautions in mind. */ public interface SimpleInstrumentListener { @@ -47,7 +50,7 @@ * <p> * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ - void enter(Probe probe); + void onEnter(Probe probe); /** * Receive notification that a program location's {@code void}-valued execution has just @@ -55,7 +58,7 @@ * <p> * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ - void returnVoid(Probe probe); + void onReturnVoid(Probe probe); /** * Receive notification that a program location's execution has just completed and returned a @@ -63,12 +66,12 @@ * <p> * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ - void returnValue(Probe probe, Object result); + void onReturnValue(Probe probe, Object result); /** * Receive notification that a program location's execution has just thrown an exception. * <p> * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ - void returnExceptional(Probe probe, Exception exception); + void onReturnExceptional(Probe probe, Exception exception); }
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/StandardInstrumentListener.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/StandardInstrumentListener.java Sun Sep 20 16:48:50 2015 -0700 @@ -29,10 +29,10 @@ import com.oracle.truffle.api.source.SourceSection; /** - * A receiver of Truffle execution events that can act on behalf of an external client. + * A receiver of Truffle AST execution events that can act on behalf of an external client. * <p> * The {@link Probe} argument provides access to the {@link SourceSection} associated with the - * event, as well as any {@link SyntaxTag}s that have been applied at that AST node. + * event, as well as any {@link SyntaxTag}s that have been applied at that program's location. * <p> * This listener is designed for clients that also require access to the AST execution state at the * time of the event. Clients that do not require access to the AST execution state should use the @@ -41,6 +41,9 @@ * Clients are free, of course, to record additional information in the listener implementation that * carries additional information about the context and reason for the particular {@link Instrument} * that is to be created from the listener. + * <p> + * Notification is fully synchronous, so overrides have performance implications. Non-trivial + * methods should be coded with Truffle guidelines and cautions in mind. */ public interface StandardInstrumentListener { @@ -49,14 +52,14 @@ * <p> * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ - void enter(Probe probe, Node node, VirtualFrame vFrame); + void onEnter(Probe probe, Node node, VirtualFrame vFrame); /** * Receive notification that an AST Node's {@code void}-valued execute method has just returned. * <p> * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ - void returnVoid(Probe probe, Node node, VirtualFrame vFrame); + void onReturnVoid(Probe probe, Node node, VirtualFrame vFrame); /** * Receive notification that an AST Node's execute method has just returned a value (boxed if @@ -64,12 +67,12 @@ * <p> * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ - void returnValue(Probe probe, Node node, VirtualFrame vFrame, Object result); + void onReturnValue(Probe probe, Node node, VirtualFrame vFrame, Object result); /** * Receive notification that an AST Node's execute method has just thrown an exception. * <p> * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ - void returnExceptional(Probe probe, Node node, VirtualFrame vFrame, Exception exception); + void onReturnExceptional(Probe probe, Node node, VirtualFrame vFrame, Exception exception); }
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/DefaultSimpleInstrumentListener.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/DefaultSimpleInstrumentListener.java Sun Sep 20 16:48:50 2015 -0700 @@ -32,15 +32,15 @@ */ public class DefaultSimpleInstrumentListener implements SimpleInstrumentListener { - public void enter(Probe probe) { + public void onEnter(Probe probe) { } - public void returnVoid(Probe probe) { + public void onReturnVoid(Probe probe) { } - public void returnValue(Probe probe, Object result) { + public void onReturnValue(Probe probe, Object result) { } - public void returnExceptional(Probe probe, Exception exception) { + public void onReturnExceptional(Probe probe, Exception exception) { } }
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/DefaultStandardInstrumentListener.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/impl/DefaultStandardInstrumentListener.java Sun Sep 20 16:48:50 2015 -0700 @@ -35,16 +35,16 @@ */ public class DefaultStandardInstrumentListener implements StandardInstrumentListener { - public void enter(Probe probe, Node node, VirtualFrame vFrame) { + public void onEnter(Probe probe, Node node, VirtualFrame vFrame) { } - public void returnVoid(Probe probe, Node node, VirtualFrame vFrame) { + public void onReturnVoid(Probe probe, Node node, VirtualFrame vFrame) { } - public void returnValue(Probe probe, Node node, VirtualFrame vFrame, Object result) { + public void onReturnValue(Probe probe, Node node, VirtualFrame vFrame, Object result) { } - public void returnExceptional(Probe probe, Node node, VirtualFrame vFrame, Exception exception) { + public void onReturnExceptional(Probe probe, Node node, VirtualFrame vFrame, Exception exception) { } }
--- a/truffle/com.oracle.truffle.sl.test/src/com/oracle/truffle/sl/test/instrument/SLInstrumentTestRunner.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.sl.test/src/com/oracle/truffle/sl/test/instrument/SLInstrumentTestRunner.java Sun Sep 20 16:48:50 2015 -0700 @@ -320,7 +320,7 @@ } @Override - public void returnValue(Probe probe, Object result) { + public void onReturnValue(Probe probe, Object result) { output.println(result); } }
--- a/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/CoverageTracker.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/CoverageTracker.java Sun Sep 20 16:48:50 2015 -0700 @@ -63,7 +63,7 @@ * <p> * <ul> * <li>"Execution call" on a node is is defined as invocation of a node method that is instrumented - * to produce the event {@link SimpleInstrumentListener#enter(Probe)};</li> + * to produce the event {@link SimpleInstrumentListener#onEnter(Probe)};</li> * <li>Execution calls are tabulated only at <em>instrumented</em> nodes, i.e. those for which * {@link Instrumenter#isInstrumentable(Node)}{@code == true};</li> * <li>Execution calls are tabulated only at nodes present in the AST when originally created; @@ -256,7 +256,7 @@ } @Override - public void enter(Probe probe) { + public void onEnter(Probe probe) { if (isEnabled()) { count++; }
--- a/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/NodeExecCounter.java Sun Sep 20 16:47:26 2015 -0700 +++ b/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/NodeExecCounter.java Sun Sep 20 16:48:50 2015 -0700 @@ -66,7 +66,7 @@ * <p> * <ul> * <li>"Execution call" on a node is is defined as invocation of a node method that is instrumented - * to produce the event {@link StandardInstrumentListener#enter(Probe, Node, VirtualFrame)};</li> + * to produce the event {@link StandardInstrumentListener#onEnter(Probe, Node, VirtualFrame)};</li> * <li>Execution calls are tabulated only at <em>instrumented</em> nodes, i.e. those for which * {@linkplain Instrumenter#isInstrumentable(Node) isInstrumentable() == true};</li> * <li>Execution calls are tabulated only at nodes present in the AST when originally created; @@ -114,7 +114,7 @@ */ private final StandardInstrumentListener instrumentListener = new DefaultStandardInstrumentListener() { @Override - public void enter(Probe probe, Node node, VirtualFrame vFrame) { + public void onEnter(Probe probe, Node node, VirtualFrame vFrame) { if (isEnabled()) { final Class<?> nodeClass = node.getClass(); /*