Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentListener.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
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 }