Mercurial > hg > graal-jvmci-8
changeset 20890:37912559d662
Truffle/Instrumentation: Javadoc work on instrument listener interfaces.
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Fri, 10 Apr 2015 17:55:09 -0700 |
parents | 0e647427eee4 |
children | 0f3d81231ecb |
files | graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTInstrumentListener.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentListener.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationNode.java |
diffstat | 3 files changed, 54 insertions(+), 15 deletions(-) [+] |
line wrap: on
line diff
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTInstrumentListener.java Fri Apr 10 16:58:26 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTInstrumentListener.java Fri Apr 10 17:55:09 2015 -0700 @@ -26,32 +26,50 @@ import com.oracle.truffle.api.frame.*; import com.oracle.truffle.api.nodes.*; +import com.oracle.truffle.api.source.*; /** - * A listener of Truffle AST runtime execution events that can collect information, examine the - * execution state at a particular node, and possibly intervene on behalf of an external tool. + * A receiver of Truffle 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 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 + * simpler {@link InstrumentListener}. + * <p> + * 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. */ public interface ASTInstrumentListener { /** * Receive notification that an AST node's execute method is about to be called. + * <p> + * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ void enter(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); /** * Receive notification that an AST Node's execute method has just returned a value (boxed if * primitive). + * <p> + * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ void returnValue(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); - }
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentListener.java Fri Apr 10 16:58:26 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentListener.java Fri Apr 10 17:55:09 2015 -0700 @@ -24,31 +24,51 @@ */ package com.oracle.truffle.api.instrument; +import com.oracle.truffle.api.source.*; + /** - * A listener of Truffle execution events that can collect information on behalf of an external - * tool. Contextual information about the source of the event, if not stored in the implementation - * of the listener, can be obtained via access to the {@link Probe} that generates the event. + * A receiver of Truffle 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. + * <p> + * This is the simplest kind of listener, suitable for clients that need no other information about + * the program's execution state at the time of the event. Clients that require access to the AST + * execution state should use {@link ASTInstrumentListener}. + * <p> + * 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. */ public interface InstrumentListener { /** - * Receive notification that an AST node's execute method is about to be called. + * Receive notification that a program location is about to be executed. + * <p> + * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ void enter(Probe probe); /** - * Receive notification that an AST Node's {@code void}-valued execute method has just returned. + * Receive notification that a program location's {@code void}-valued execution has just + * completed. + * <p> + * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ void returnVoid(Probe probe); /** - * Receive notification that an AST Node's execute method has just returned a value (boxed if - * primitive). + * Receive notification that a program location's execution has just completed and returned a + * value (boxed if primitive). + * <p> + * <strong>Synchronous</strong>: Truffle execution waits until the call returns. */ void returnValue(Probe probe, Object result); /** - * Receive notification that an AST Node's execute method has just thrown an exception. + * 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); }
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationNode.java Fri Apr 10 16:58:26 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationNode.java Fri Apr 10 17:55:09 2015 -0700 @@ -28,8 +28,9 @@ import com.oracle.truffle.api.nodes.*; /** - * A marker interface for Truffle {@linkplain Node nodes} that support <em>Instrumentation</em> and - * are should not be part of any Guest Language execution semantics. + * A marker interface for Truffle {@linkplain Node nodes} that internally implement the + * <em>Instrumentation Framework</em>. Such nodes should not be part of any Guest Language execution + * semantics, and should in general not be visible to ordinary Instrumentation clients. */ public interface InstrumentationNode { @@ -39,7 +40,8 @@ String instrumentationInfo(); /** - * Events at a Truffle node that get propagated through the Instrumentation Framework. + * Events that propagate through the {@linkplain InstrumentationNode implementation nodes} of + * the Instrumentation Framework, not visible in this form to Instrumentation clients. */ interface TruffleEvents { @@ -62,6 +64,5 @@ * An AST Node's execute method has just thrown an exception. */ void returnExceptional(Node node, VirtualFrame vFrame, Exception exception); - } }