Mercurial > hg > graal-jvmci-8
comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Wrapper.java @ 15605:bb9473723904
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}. |