# HG changeset patch # User Michael Van De Vanter # Date 1442696202 25200 # Node ID 776dc0a09749f55a8deff7d4bb9e138baf95b6cc # Parent 964e789e17f78b6954c96d4dc71ac9fe1fe9aa68 Truffle/Instrumentation: Javadoc diff -r 964e789e17f7 -r 776dc0a09749 truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrumenter.java --- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrumenter.java Sat Sep 19 13:26:06 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrumenter.java Sat Sep 19 13:56:42 2015 -0700 @@ -110,7 +110,8 @@ } /** - * Returns {@code true} if the node can be "instrumented" by {@linkplain #probe(Node) probing}. + * Returns {@code true} if the AST node can be "instrumented" by {@linkplain #probe(Node) + * Probing}. *

* Note: instrumentation requires a appropriate {@linkplain #createWrapperNode(Node) * WrapperNode}. @@ -120,11 +121,11 @@ } /** - * For nodes that are {@linkplain #isInstrumentable() instrumentable}, this method must return - * an {@linkplain Node AST node} that: + * For AST nodes that are {@linkplain #isInstrumentable() instrumentable}, returns a + * wrapper node that: *

    *
  1. implements {@link WrapperNode}
    2. - *
  2. has the node argument as it's child, and
    3. + *
  3. has the node as its single child, and
    4. *
  4. whose type is safe for replacement of the node in the parent.
    5. *
* @@ -135,13 +136,19 @@ } /** - * Enables {@linkplain Instrument instrumentation} of a node, where the node is presumed to be - * part of a well-formed Truffle AST that is not being executed. If this node has not already - * been probed, modifies the AST by inserting a {@linkplain WrapperNode wrapper node} between - * the node and its parent; the wrapper node must be provided by implementations of - * {@link Node#createWrapperNode()}. No more than one {@link Probe} may be associated with a - * node, so a {@linkplain WrapperNode wrapper} may not wrap another {@linkplain WrapperNode - * wrapper}. + * Prepares an AST node for {@linkplain Instrument instrumentation}, where the node is presumed + * to be part of a well-formed Truffle AST that has not yet been executed. + *

+ * Probing a node is idempotent: + *

+ * It is a runtime error to attempt Probing an AST node with no parent. * * @return a (possibly newly created) {@link Probe} associated with this node. * @throws ProbeException (unchecked) when a probe cannot be created, leaving the AST unchanged diff -r 964e789e17f7 -r 776dc0a09749 truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java --- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java Sat Sep 19 13:26:06 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Probe.java Sat Sep 19 13:56:42 2015 -0700 @@ -43,61 +43,21 @@ /** * A binding between: *
    - *
  1. A program location in an executing Truffle AST (corresponding to a {@link SourceSection}), - * and
    2. - *
  2. A dynamically managed collection of "attached" {@linkplain Instrument Instruments} that - * receive event notifications on behalf of external clients.
    3. + *
  3. A guest language program location in an executing Truffle AST (corresponding to a + * {@link SourceSection}), and
    4. + *
  4. A dynamically managed collection of attached {@linkplain Instrument Instruments} + * that receive event notifications from the Probe's AST location on behalf of external clients.
    5. *
+ * Note:The relationship must be with an AST location, not a specific + * {@link Node}, because ASTs are routinely cloned at runtime. An AST location is + * best represented as the {@link SourceSection} from which the original AST Node was created. *

* Client-oriented documentation for the use of Probes is available online at https://wiki.openjdk.java. * net/display/Graal/Finding+Probes *

- *

Implementation notes:

- *

- *

- * + * @see Instrumenter * @see Instrument * @see ASTProber * @see ProbeListener @@ -141,7 +101,51 @@ @CompilationFinal private boolean isAfterTrapActive = false; /** - * Intended for use only by {@link ProbeNode}. + * Constructor for use only by {@link ProbeNode}. + *

+ *

Probe Implementation notes:

+ *

+ *

*/ Probe(Instrumenter instrumenter, Class l, ProbeNode probeNode, SourceSection sourceSection) { this.instrumenter = instrumenter; @@ -151,22 +155,6 @@ } /** - * Is this node tagged as belonging to a particular human-sensible category of language - * constructs? - */ - public boolean isTaggedAs(SyntaxTag tag) { - assert tag != null; - return tags.contains(tag); - } - - /** - * In which user-sensible categories has this node been tagged (empty set if none). - */ - public Collection getSyntaxTags() { - return Collections.unmodifiableCollection(tags); - } - - /** * Adds a {@linkplain SyntaxTag tag} to the set of tags associated with this {@link Probe}; * {@code no-op} if already in the set. */ @@ -198,6 +186,23 @@ } /** + * Is the Probed node tagged as belonging to a particular human-sensible category of + * language constructs? + */ + public boolean isTaggedAs(SyntaxTag tag) { + assert tag != null; + return tags.contains(tag); + } + + /** + * In which user-sensible categories has the Probed node been tagged ( + * empty set if none). + */ + public Collection getSyntaxTags() { + return Collections.unmodifiableCollection(tags); + } + + /** * Adds instrumentation at this Probe. * * @param instrument an instrument not yet attached to a probe @@ -221,8 +226,8 @@ } /** - * Gets the {@link SourceSection} associated with the Guest Language AST node being - * instrumented, possibly {@code null}. + * Gets the {@link SourceSection} associated with the Probed AST node, possibly + * {@code null}. */ public SourceSection getProbedSourceSection() { return sourceSection;