comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java @ 16857:7bfbad29d331

Truffle/Instrumentation: Javadoc cleanups and minor corrections.
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 18 Aug 2014 21:03:41 -0700
parents 7833417c8172
children c4f374adce13
comparison
equal deleted inserted replaced
16856:7833417c8172 16857:7bfbad29d331
43 * <p> 43 * <p>
44 * Probe methods must be amenable to Truffle/Graal inlining on the assumption that the collection of 44 * Probe methods must be amenable to Truffle/Graal inlining on the assumption that the collection of
45 * attached instruments seldom changes. The assumption is invalidated when instruments are added or 45 * attached instruments seldom changes. The assumption is invalidated when instruments are added or
46 * removed, but some instruments may change their internal state in such a way that the assumption 46 * removed, but some instruments may change their internal state in such a way that the assumption
47 * should also be invalidated. 47 * should also be invalidated.
48 * <p>
49 * <strong>Disclaimer:</strong> experimental interface under development. In particular, the
50 * <em>notify</em> methods must be migrated to another interface.
51 * 48 *
52 * @see Instrument 49 * @see Instrument
53 * @see Wrapper 50 * @see Wrapper
54 */ 51 */
55 public interface Probe extends ExecutionEvents, SyntaxTagged { 52 public interface Probe extends ExecutionEvents, SyntaxTagged {
56 53
57 /** 54 /**
58 * Get the {@link SourceSection} associated with this probe. This is no longer uniquely 55 * Get the {@link SourceSection} in some Truffle AST associated with this probe.
59 * associated.
60 * 56 *
61 * @return The source associated with this probe. 57 * @return The source associated with this probe.
62 */ 58 */
63 SourceSection getSourceLocation(); 59 SourceSection getSourceLocation();
64 60
65 /** 61 /**
66 * Mark this probe as being associated with an AST node in some category useful for debugging 62 * Mark this probe as belonging to some tool-related category that can be used to guide tool
67 * and other tools. 63 * behavior at an associated AST node. For example, a debugger might add the tag
64 * {@link StandardSyntaxTag#STATEMENT} as a way of configuring where execution should stop when
65 * stepping.
68 */ 66 */
69 void tagAs(SyntaxTag tag); 67 void tagAs(SyntaxTag tag);
70 68
71 /** 69 /**
72 * Adds an instrument to this probe. 70 * Adds an {@link Instrument} to this probe's collection. No check is made to see if the same
71 * instrument has already been added.
72 *
73 * @param newInstrument The instrument to add to this probe.
73 */ 74 */
74 void addInstrument(Instrument newInstrument); 75 void addInstrument(Instrument newInstrument);
75 76
76 /** 77 /**
77 * Removes an instrument from this probe. 78 * Removes the given instrument from the probe's collection.
79 *
80 * @param oldInstrument The instrument to remove from this probe.
81 * @throws RuntimeException if no matching instrument has been attached.
78 */ 82 */
79 void removeInstrument(Instrument oldInstrument); 83 void removeInstrument(Instrument oldInstrument) throws RuntimeException;
80 84
81 } 85 }