Mercurial > hg > graal-jvmci-8

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/AdvancedInstrumentRootFactory.java @ 21406:b4aca5ec3f10

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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