Mercurial > hg > graal-compiler
diff 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 |
line wrap: on
line diff
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/AdvancedInstrumentRootFactory.java Fri May 15 23:03:42 2015 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/AdvancedInstrumentRootFactory.java Sun May 17 18:30:43 2015 -0700 @@ -38,9 +38,21 @@ public interface AdvancedInstrumentRootFactory { /** - * Provider of {@linkplain AdvancedInstrumentRoot AST fragment} instances for efficient - * execution via instrumentation, subject to full Truffle optimization, at a {@linkplain Probe - * Probed} site in a guest-language AST. + * Provider of {@linkplain AdvancedInstrumentRoot AST fragment} instances to be executed by the + * Instrumentation Framework at a {@linkplain Probe Probed} site in a guest-language AST. + * <p> + * <strong>Notes:</strong> + * <ul> + * <li>Once the factory has produced an AST fragment at a particular {@linkplain Node AST Node}, + * it will not be called again at that Node.</li> + * <li>In some use cases, for example to implement a breakpoint at a specific program location, + * the Probe argument will be the same for every call. Each Node argument will represent the + * same program location associated with the Probe, but in different clones of the AST.</li> + * <li>In other use cases, for example to implement a breakpoint at any Node with a particular + * {@linkplain SyntaxTag tag}, both the Probe and Node argument may differ. Implementations that + * are sensitive to the lexical context in which the AST fragment will be evaluated must take + * care to build a new, possibly different AST fragment for each request.</li> + * </ul> * * @param probe the Probe to which the Instrument requesting the AST fragment is attached * @param node the guest-language AST location that is the context in which the requesting