Mercurial > hg > truffle

comparison truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SimpleInstrumentListener.java @ 22230:3f2052afcb6d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: rename the methods in the Instrument listener classes to use the "on" convention, e.g. onEnter(), add Javadoc
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Sun, 20 Sep 2015 16:48:50 -0700
parents dc83cc1f94f2
children e7643754d982
comparison
equal deleted inserted replaced
22229:a4ac9f2ff2bf 22230:3f2052afcb6d
25 package com.oracle.truffle.api.instrument; 25 package com.oracle.truffle.api.instrument;
26 26
27 import com.oracle.truffle.api.source.SourceSection; 27 import com.oracle.truffle.api.source.SourceSection;
28 28
29 /** 29 /**
30 * A receiver of Truffle execution events that can act on behalf of an external client. 30 * A receiver of Truffle AST execution events that can act on behalf of an external client.
31 * <p> 31 * <p>
32 * The {@link Probe} instance provides access to the {@link SourceSection} associated with the 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. 33 * event, as well as any {@link SyntaxTag}s that have been applied at that program's location.
34 * <p> 34 * <p>
35 * This is the simplest kind of listener, suitable for clients that need no other information about 35 * This is the simplest kind of listener, suitable for clients that need no other information about
37 * execution state should use {@link StandardInstrumentListener}. 37 * execution state should use {@link StandardInstrumentListener}.
38 * <p> 38 * <p>
39 * Clients are free, of course, to record additional information in the listener implementation that 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} 40 * carries additional information about the context and reason for the particular {@link Instrument}
41 * that is to be created from the listener. 41 * that is to be created from the listener.
42 * <p>
43 * Notification is fully synchronous, so overrides have performance implications. Non-trivial
44 * methods should be coded with Truffle guidelines and cautions in mind.
42 */ 45 */
43 public interface SimpleInstrumentListener { 46 public interface SimpleInstrumentListener {
44 47
45 /** 48 /**
46 * Receive notification that a program location is about to be executed. 49 * Receive notification that a program location is about to be executed.
47 * <p> 50 * <p>
48 * <strong>Synchronous</strong>: Truffle execution waits until the call returns. 51 * <strong>Synchronous</strong>: Truffle execution waits until the call returns.
49 */ 52 */
50 void enter(Probe probe); 53 void onEnter(Probe probe);
51 54
52 /** 55 /**
53 * Receive notification that a program location's {@code void}-valued execution has just 56 * Receive notification that a program location's {@code void}-valued execution has just
54 * completed. 57 * completed.
55 * <p> 58 * <p>
56 * <strong>Synchronous</strong>: Truffle execution waits until the call returns. 59 * <strong>Synchronous</strong>: Truffle execution waits until the call returns.
57 */ 60 */
58 void returnVoid(Probe probe); 61 void onReturnVoid(Probe probe);
59 62
60 /** 63 /**
61 * Receive notification that a program location's execution has just completed and returned a 64 * Receive notification that a program location's execution has just completed and returned a
62 * value (boxed if primitive). 65 * value (boxed if primitive).
63 * <p> 66 * <p>
64 * <strong>Synchronous</strong>: Truffle execution waits until the call returns. 67 * <strong>Synchronous</strong>: Truffle execution waits until the call returns.
65 */ 68 */
66 void returnValue(Probe probe, Object result); 69 void onReturnValue(Probe probe, Object result);
67 70
68 /** 71 /**
69 * Receive notification that a program location's execution has just thrown an exception. 72 * Receive notification that a program location's execution has just thrown an exception.
70 * <p> 73 * <p>
71 * <strong>Synchronous</strong>: Truffle execution waits until the call returns. 74 * <strong>Synchronous</strong>: Truffle execution waits until the call returns.
72 */ 75 */
73 void returnExceptional(Probe probe, Exception exception); 76 void onReturnExceptional(Probe probe, Exception exception);
74 } 77 }