Mercurial > hg > graal-jvmci-8
changeset 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 | cdb5eda3a4b5 |
children | 36285949c1d5 |
files | graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/AdvancedInstrumentRootFactory.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java |
diffstat | 2 files changed, 16 insertions(+), 4 deletions(-) [+] |
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
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Fri May 15 23:03:42 2015 +0200 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Sun May 17 18:30:43 2015 -0700 @@ -31,7 +31,7 @@ import com.oracle.truffle.api.source.*; // TODO (mlvdv) these statics should not be global. Move them to some kind of context. -// TODO (mlvdv) migrate factory into .impl (together with Probe)? break out nested classes? +// TODO (mlvdv) migrate factory (together with Probe)? break out nested classes? /** * A <em>binding</em> between: