Mercurial > hg > graal-compiler
comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentListener.java @ 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 | a5b09092003a |
children |
comparison
equal
deleted
inserted
replaced
20889:0e647427eee4 | 20890:37912559d662 |
---|---|
22 * or visit www.oracle.com if you need additional information or have any | 22 * or visit www.oracle.com if you need additional information or have any |
23 * questions. | 23 * questions. |
24 */ | 24 */ |
25 package com.oracle.truffle.api.instrument; | 25 package com.oracle.truffle.api.instrument; |
26 | 26 |
27 import com.oracle.truffle.api.source.*; | |
28 | |
27 /** | 29 /** |
28 * A listener of Truffle execution events that can collect information on behalf of an external | 30 * A receiver of Truffle execution events that can act on behalf of an external client. |
29 * tool. Contextual information about the source of the event, if not stored in the implementation | 31 * <p> |
30 * of the listener, can be obtained via access to the {@link Probe} that generates the event. | 32 * The {@link Probe} instance provides access to the {@link SourceSection} associated with the |
33 * event, as well as any {@link SyntaxTag}s that have been applied at that program's location. | |
34 * <p> | |
35 * This is the simplest kind of listener, suitable for clients that need no other information about | |
36 * the program's execution state at the time of the event. Clients that require access to the AST | |
37 * execution state should use {@link ASTInstrumentListener}. | |
38 * <p> | |
39 * Clients are free, of course, to record additional information in the listener implementation that | |
40 * carries additional information about the context and reason for the particular {@link Instrument} | |
41 * that is to be created from the listener. | |
31 */ | 42 */ |
32 public interface InstrumentListener { | 43 public interface InstrumentListener { |
33 | 44 |
34 /** | 45 /** |
35 * Receive notification that an AST node's execute method is about to be called. | 46 * Receive notification that a program location is about to be executed. |
47 * <p> | |
48 * <strong>Synchronous</strong>: Truffle execution waits until the call returns. | |
36 */ | 49 */ |
37 void enter(Probe probe); | 50 void enter(Probe probe); |
38 | 51 |
39 /** | 52 /** |
40 * Receive notification that an AST Node's {@code void}-valued execute method has just returned. | 53 * Receive notification that a program location's {@code void}-valued execution has just |
54 * completed. | |
55 * <p> | |
56 * <strong>Synchronous</strong>: Truffle execution waits until the call returns. | |
41 */ | 57 */ |
42 void returnVoid(Probe probe); | 58 void returnVoid(Probe probe); |
43 | 59 |
44 /** | 60 /** |
45 * Receive notification that an AST Node's execute method has just returned a value (boxed if | 61 * Receive notification that a program location's execution has just completed and returned a |
46 * primitive). | 62 * value (boxed if primitive). |
63 * <p> | |
64 * <strong>Synchronous</strong>: Truffle execution waits until the call returns. | |
47 */ | 65 */ |
48 void returnValue(Probe probe, Object result); | 66 void returnValue(Probe probe, Object result); |
49 | 67 |
50 /** | 68 /** |
51 * Receive notification that an AST Node's execute method has just thrown an exception. | 69 * Receive notification that a program location's execution has just thrown an exception. |
70 * <p> | |
71 * <strong>Synchronous</strong>: Truffle execution waits until the call returns. | |
52 */ | 72 */ |
53 void returnExceptional(Probe probe, Exception exception); | 73 void returnExceptional(Probe probe, Exception exception); |
54 } | 74 } |