Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java @ 15779:8c34e2cc4add

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: significant reorganization of the instrumentation framework's implementation and connection to the runtime ExecutionContext, with some new features, including a Tag-based "trap" mechanisms.
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 19 May 2014 17:14:36 -0700
parents bb9473723904
children b4e38f4ca414
comparison
equal deleted inserted replaced
15632:dcaf3993ad17 15779:8c34e2cc4add
29 import com.oracle.truffle.api.frame.*; 29 import com.oracle.truffle.api.frame.*;
30 import com.oracle.truffle.api.instrument.impl.*; 30 import com.oracle.truffle.api.instrument.impl.*;
31 import com.oracle.truffle.api.nodes.*; 31 import com.oracle.truffle.api.nodes.*;
32 32
33 /** 33 /**
34 * A receiver of Truffle AST {@link ExecutionEvents}, propagated from a {@link Probe} to which the 34 * A receiver of Truffle AST runtime {@link ExecutionEvents}, propagated from the {@link Probe} to
35 * instrument is attached, for the benefit of associated <em>tools</em>. 35 * which the instrument is attached, for the benefit of associated <em>tools</em>.
36 * <p> 36 * <p>
37 * Guidelines for implementing Instruments, with particular attention to avoiding undesired runtime 37 * Guidelines for implementing {@link Instrument}s, with particular attention to minimize runtime
38 * performance overhead: 38 * performance overhead:
39 * <ol> 39 * <ol>
40 * <li>Extend {@link Instrument} and override only the event handling methods for which some action 40 * <li>Extend this abstract class and override only the {@linkplain ExecutionEvents event handling
41 * is needed.</li> 41 * methods} for which intervention is needed.</li>
42 * <li>Instruments are Truffle {@link Node}s and should be coded as much as possible in the desired 42 * <li>Instruments are Truffle {@link Node}s and should be coded as much as possible in the desired
43 * <em>Truffle style</em>, documented more thoroughly elsewhere.</li> 43 * <em>Truffle style</em>, documented more thoroughly elsewhere.</li>
44 * <li>Maintain as little state as possible.</li> 44 * <li>Maintain as little state as possible.</li>
45 * <li>If state is necessary, make it {@code final} if possible.</li> 45 * <li>If state is necessary, make object fields {@code final} if at all possible.</li>
46 * <li>If non-final state is necessary, annotate it as {@link CompilationFinal} and call 46 * <li>If non-final object-valued state is necessary, annotate it as {@link CompilationFinal} and
47 * {@linkplain InstrumentationNode#notifyProbeChanged(Instrument)} whenever it is modified.</li> 47 * call {@linkplain InstrumentationNode#notifyProbeChanged(Instrument)} whenever it is modified.</li>
48 * <li>Never store a {@link Frame} value in a field.</li> 48 * <li>Never store a {@link Frame} value in a field.</li>
49 * <li>Minimize computation in standard execution paths.</li> 49 * <li>Minimize computation in standard execution paths.</li>
50 * <li>Callbacks to tools should be made via callbacks provided at construction and stored in 50 * <li>If runtime calls must be made back to a tool, construct the instrument with a callback stored
51 * {@code final} fields.</li> 51 * in a {@code final} field.</li>
52 * <li>Tool callback methods should usually be annotated as {@link SlowPath} to prevent them from 52 * <li>Tool methods called by the instrument should be annotated as {@link SlowPath} to prevent them
53 * being inlined into fast execution paths.</li> 53 * from being inlined into fast execution paths.</li>
54 * <li>If computation is needed, and if performance is important, then the computation is best 54 * <li>If computation in the execution path is needed, and if performance is important, then the
55 * expressed as a guest language AST and evaluated using standard Truffle mechanisms so that 55 * computation is best expressed as a guest language AST and evaluated using standard Truffle
56 * standard Truffle optimizations can be applied.</li> 56 * mechanisms so that standard Truffle optimizations can be applied.</li>
57 * </ol> 57 * </ol>
58 * <p> 58 * <p>
59 * Guidelines for attachment to a {@link Probe}: 59 * Guidelines for attachment to a {@link Probe}:
60 * <ol> 60 * <ol>
61 * <li>An Instrument instance must only attached to a single {@link Probe}, each of which is 61 * <li>An Instrument instance must only attached to a single {@link Probe}, each of which is
63 * (initially) to a specific {@linkplain Node Truffle AST node}.</li> 63 * (initially) to a specific {@linkplain Node Truffle AST node}.</li>
64 * <li>When the AST containing such a node is copied at runtime, the {@link Probe} will be shared by 64 * <li>When the AST containing such a node is copied at runtime, the {@link Probe} will be shared by
65 * every copy, and so the Instrument will receive events corresponding to the intended syntactic 65 * every copy, and so the Instrument will receive events corresponding to the intended syntactic
66 * unit of code, independent of which AST copy is being executed.</li> 66 * unit of code, independent of which AST copy is being executed.</li>
67 * </ol> 67 * </ol>
68 * <p>
69 * Guidelines for handling {@link ExecutionEvents}:
70 * <ol>
71 * <li>Separate event methods are defined for each kind of possible return: object-valued,
72 * primitive-valued, void-valued, and exceptional.</li>
73 * <li>Override "leave*" primitive methods if the language implementation returns primitives and the
74 * instrument should avoid boxing them.</li>
75 * <li>On the other hand, if boxing all primitives for instrumentation is desired, it is only
76 * necessary to override the object-valued return methods, since the default implementation of each
77 * primitive-valued return method is to box the value and forward it to the object-valued return
78 * method.</li>
79 * </ol>
68 * 80 *
69 * <p> 81 * <p>
70 * <strong>Disclaimer:</strong> experimental; under development. 82 * <strong>Disclaimer:</strong> experimental; under development.
71 * 83 *
72 * @see Probe 84 * @see Probe
73 * @see ASTNodeProber 85 * @see ASTNodeProber
74 */ 86 */
75 public class Instrument extends InstrumentationNode { 87 public abstract class Instrument extends InstrumentationNode {
76 88
77 protected Instrument() { 89 protected Instrument() {
78 } 90 }
79 91
80 public void enter(Node astNode, VirtualFrame frame) { 92 public void enter(Node astNode, VirtualFrame frame) {