Mercurial > hg > graal-jvmci-8
comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/AdvancedInstrumentRootFactory.java @ 21406:b4aca5ec3f10
Truffle/Instrumentation: Javadoc commentary
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Sun, 17 May 2015 18:30:43 -0700 |
parents | e34bc00733d1 |
children | 28cbfacd0518 |
comparison
equal
deleted
inserted
replaced
21405:cdb5eda3a4b5 | 21406:b4aca5ec3f10 |
---|---|
36 * @see AdvancedInstrumentRoot | 36 * @see AdvancedInstrumentRoot |
37 */ | 37 */ |
38 public interface AdvancedInstrumentRootFactory { | 38 public interface AdvancedInstrumentRootFactory { |
39 | 39 |
40 /** | 40 /** |
41 * Provider of {@linkplain AdvancedInstrumentRoot AST fragment} instances for efficient | 41 * Provider of {@linkplain AdvancedInstrumentRoot AST fragment} instances to be executed by the |
42 * execution via instrumentation, subject to full Truffle optimization, at a {@linkplain Probe | 42 * Instrumentation Framework at a {@linkplain Probe Probed} site in a guest-language AST. |
43 * Probed} site in a guest-language AST. | 43 * <p> |
44 * <strong>Notes:</strong> | |
45 * <ul> | |
46 * <li>Once the factory has produced an AST fragment at a particular {@linkplain Node AST Node}, | |
47 * it will not be called again at that Node.</li> | |
48 * <li>In some use cases, for example to implement a breakpoint at a specific program location, | |
49 * the Probe argument will be the same for every call. Each Node argument will represent the | |
50 * same program location associated with the Probe, but in different clones of the AST.</li> | |
51 * <li>In other use cases, for example to implement a breakpoint at any Node with a particular | |
52 * {@linkplain SyntaxTag tag}, both the Probe and Node argument may differ. Implementations that | |
53 * are sensitive to the lexical context in which the AST fragment will be evaluated must take | |
54 * care to build a new, possibly different AST fragment for each request.</li> | |
55 * </ul> | |
44 * | 56 * |
45 * @param probe the Probe to which the Instrument requesting the AST fragment is attached | 57 * @param probe the Probe to which the Instrument requesting the AST fragment is attached |
46 * @param node the guest-language AST location that is the context in which the requesting | 58 * @param node the guest-language AST location that is the context in which the requesting |
47 * Instrument must execute the AST fragment. | 59 * Instrument must execute the AST fragment. |
48 * @return a newly created AST fragment suitable for execution, via instrumentation, in the | 60 * @return a newly created AST fragment suitable for execution, via instrumentation, in the |