Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTInstrumentListener.java @ 20890:37912559d662

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 a5b09092003a
children 0f3d81231ecb
comparison
equal deleted inserted replaced
20889:0e647427eee4 20890:37912559d662
24 */ 24 */
25 package com.oracle.truffle.api.instrument; 25 package com.oracle.truffle.api.instrument;
26 26
27 import com.oracle.truffle.api.frame.*; 27 import com.oracle.truffle.api.frame.*;
28 import com.oracle.truffle.api.nodes.*; 28 import com.oracle.truffle.api.nodes.*;
29 import com.oracle.truffle.api.source.*;
29 30
30 /** 31 /**
31 * A listener of Truffle AST runtime execution events that can collect information, examine the 32 * A receiver of Truffle execution events that can act on behalf of an external client.
32 * execution state at a particular node, and possibly intervene on behalf of an external tool. 33 * <p>
34 * The {@link Probe} argument provides access to the {@link SourceSection} associated with the
35 * event, as well as any {@link SyntaxTag}s that have been applied at that AST location.
36 * <p>
37 * This listener is designed for clients that also require access to the AST execution state at the
38 * time of the event. Clients that do not require access to the AST execution state should use the
39 * simpler {@link InstrumentListener}.
40 * <p>
41 * Clients are free, of course, to record additional information in the listener implementation that
42 * carries additional information about the context and reason for the particular {@link Instrument}
43 * that is to be created.
33 */ 44 */
34 public interface ASTInstrumentListener { 45 public interface ASTInstrumentListener {
35 46
36 /** 47 /**
37 * Receive notification that an AST node's execute method is about to be called. 48 * Receive notification that an AST node's execute method is about to be called.
49 * <p>
50 * <strong>Synchronous</strong>: Truffle execution waits until the call returns.
38 */ 51 */
39 void enter(Probe probe, Node node, VirtualFrame vFrame); 52 void enter(Probe probe, Node node, VirtualFrame vFrame);
40 53
41 /** 54 /**
42 * Receive notification that an AST Node's {@code void}-valued execute method has just returned. 55 * Receive notification that an AST Node's {@code void}-valued execute method has just returned.
56 * <p>
57 * <strong>Synchronous</strong>: Truffle execution waits until the call returns.
43 */ 58 */
44 void returnVoid(Probe probe, Node node, VirtualFrame vFrame); 59 void returnVoid(Probe probe, Node node, VirtualFrame vFrame);
45 60
46 /** 61 /**
47 * Receive notification that an AST Node's execute method has just returned a value (boxed if 62 * Receive notification that an AST Node's execute method has just returned a value (boxed if
48 * primitive). 63 * primitive).
64 * <p>
65 * <strong>Synchronous</strong>: Truffle execution waits until the call returns.
49 */ 66 */
50 void returnValue(Probe probe, Node node, VirtualFrame vFrame, Object result); 67 void returnValue(Probe probe, Node node, VirtualFrame vFrame, Object result);
51 68
52 /** 69 /**
53 * Receive notification that an AST Node's execute method has just thrown an exception. 70 * Receive notification that an AST Node's execute method has just thrown an exception.
71 * <p>
72 * <strong>Synchronous</strong>: Truffle execution waits until the call returns.
54 */ 73 */
55 void returnExceptional(Probe probe, Node node, VirtualFrame vFrame, Exception exception); 74 void returnExceptional(Probe probe, Node node, VirtualFrame vFrame, Exception exception);
56
57 } 75 }