Mercurial > hg > graal-jvmci-8

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Wrapper.java @ 15605:bb9473723904

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: - Merge instrumentation support into the general execution context; remove separate Instrumentation interface and implementation - Generalize the ?tagging? mechanism for extensibility: the enum PhylumTag is now an interface, and the standard tags moved to the new enum StandardTag - A new ?trap? mechanism interrupts program execution at any probed node holding a specified PhylumTag; this replaces some other special-purpose code. - Refine several interface by factoring out callback methods and simplifying collaboration among key implementation classes.
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 12 May 2014 20:17:25 -0700
parents 0c6d8a08e31b
children 50d79ad439f1
comparison
equal deleted inserted replaced
15486:8f09b84f325f 15605:bb9473723904
31 * particular node. 31 * particular node.
32 * <p> 32 * <p>
33 * A wrapper <em>decorates</em> an AST node (its <em>child</em>) by acting as a transparent 33 * A wrapper <em>decorates</em> an AST node (its <em>child</em>) by acting as a transparent
34 * <em>proxy</em> for the child with respect to Truffle execution semantics. 34 * <em>proxy</em> for the child with respect to Truffle execution semantics.
35 * <p> 35 * <p>
36 * A wrapper is also expected to notify its associated {@link Probe} when certain 36 * A wrapper is also expected to notify its associated {@link Probe} when {@link ExecutionEvents}
37 * {@link ExecutionEvents} occur at the wrapper during program execution. 37 * occur at the wrapper during program execution.
38 * <p> 38 * <p>
39 * The wrapper's {@link Probe} is shared by every copy of the wrapper made when the AST is copied. 39 * The wrapper's {@link Probe} is shared by every copy of the wrapper made when the AST is copied.
40 * <p> 40 * <p>
41 * Wrappers methods must be amenable to Truffle/Graal inlining. 41 * Wrapper implementation guidelines:
42 * <ol>
43 * <li>Every guest language implementation should include a Wrapper implementation; usually only one
44 * is needed.</li>
45 * <li>The Wrapper type should descend from the <em>language-specific node class</em> of the guest
46 * language.</li>
47 * <li>The Wrapper must have a single {@code @Child private <guestLanguage>Node child} field.</li>
48 * <li>The Wrapper must act as a <em>proxy</em> for its child, which means implementing every
49 * possible <em>execute-</em> method that gets called on guest language AST node types by their
50 * parents, and passing along each call to its child.</li>
51 * <li>The Wrapper must have a single {@code private final Probe probe} to which an optional probe
52 * can be attached during node construction.</li>
53 * <li>Wrapper methods must also notify its attached {@link Probe}, if any, in terms of standard
54 * {@link ExecutionEvents}.</li>
55 * <li>Most importantly, Wrappers must be implemented so that Truffle optimization will reduce their
56 * runtime overhead to zero when there is no probe attached or when a probe has no attached
57 * {@link Instrument}s.</li>
58 * </ol>
42 * <p> 59 * <p>
43 * <strong>Disclaimer:</strong> experimental interface under development. 60 * <strong>Disclaimer:</strong> experimental interface under development.
61 *
62 * @see Probe
63 * @see ExecutionEvents
44 */ 64 */
45 public interface Wrapper extends PhylumTagged { 65 public interface Wrapper extends PhylumTagged {
46 66
47 /** 67 /**
48 * Gets the AST node being instrumented, which should never be an instance of {@link Wrapper}. 68 * Gets the AST node being instrumented, which should never be an instance of {@link Wrapper}.