Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java @ 15450:be0c151d912b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: API revisions
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Tue, 29 Apr 2014 12:05:58 -0700
parents 0c6d8a08e31b
children bb9473723904
comparison
equal deleted inserted replaced
15281:041156bb59b2 15450:be0c151d912b
1 /* 1 /*
2 * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. 2 * Copyright (c) 2013, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 * 4 *
5 * This code is free software; you can redistribute it and/or modify it 5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as 6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this 7 * published by the Free Software Foundation. Oracle designates this
22 * or visit www.oracle.com if you need additional information or have any 22 * or visit www.oracle.com if you need additional information or have any
23 * questions. 23 * questions.
24 */ 24 */
25 package com.oracle.truffle.api.instrument; 25 package com.oracle.truffle.api.instrument;
26 26
27 import com.oracle.truffle.api.CompilerDirectives.CompilationFinal;
28 import com.oracle.truffle.api.CompilerDirectives.SlowPath;
29 import com.oracle.truffle.api.frame.*;
30 import com.oracle.truffle.api.instrument.impl.*;
31 import com.oracle.truffle.api.nodes.*;
32
27 /** 33 /**
28 * A receiver of Truffle AST {@link ExecutionEvents}, propagated from a {@link Probe} to which the 34 * A receiver of Truffle AST {@link ExecutionEvents}, propagated from a {@link Probe} to which the
29 * instrument is attached. 35 * instrument is attached, for the benefit of associated <em>tools</em>.
30 * <p> 36 * <p>
31 * <strong>Disclaimer:</strong> experimental interface under development. 37 * Guidelines for implementing Instruments, with particular attention to avoiding undesired runtime
38 * performance overhead:
39 * <ol>
40 * <li>Extend {@link Instrument} and override only the event handling methods for which some action
41 * is needed.</li>
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>
44 * <li>Maintain as little state as possible.</li>
45 * <li>If state is necessary, make it {@code final} if possible.</li>
46 * <li>If non-final state is necessary, annotate it as {@link CompilationFinal} and call
47 * {@linkplain InstrumentationNode#notifyProbeChanged(Instrument)} whenever it is modified.</li>
48 * <li>Never store a {@link Frame} value in a field.</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
51 * {@code final} fields.</li>
52 * <li>Tool callback methods should usually be annotated as {@link SlowPath} to prevent them from
53 * being inlined into fast execution paths.</li>
54 * <li>If computation is needed, and if performance is important, then the computation is best
55 * expressed as a guest language AST and evaluated using standard Truffle mechanisms so that
56 * standard Truffle optimizations can be applied.</li>
57 * </ol>
58 * <p>
59 * Guidelines for attachment to a {@link Probe}:
60 * <ol>
61 * <li>An Instrument instance must only attached to a single {@link Probe}, each of which is
62 * associated uniquely with a specific syntactic unit of a guest language program, and thus
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
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>
67 * </ol>
68 *
69 * <p>
70 * <strong>Disclaimer:</strong> experimental; under development.
71 *
72 * @see Instrumentation
73 * @see Probe
74 * @see Instrument
75 * @see ASTNodeProber
32 */ 76 */
33 public interface Instrument extends ExecutionEvents { 77 public class Instrument extends InstrumentationNode {
34 78
35 /** 79 protected Instrument() {
36 * @return the {@link Probe} to which this instrument is attached. 80 }
37 */ 81
38 Probe getProbe(); 82 public void enter(Node astNode, VirtualFrame frame) {
83 }
84
85 public void leave(Node astNode, VirtualFrame frame) {
86 }
87
88 public void leave(Node astNode, VirtualFrame frame, boolean result) {
89 leave(astNode, frame, (Object) result);
90 }
91
92 public void leave(Node astNode, VirtualFrame frame, byte result) {
93 leave(astNode, frame, (Object) result);
94 }
95
96 public void leave(Node astNode, VirtualFrame frame, short result) {
97 leave(astNode, frame, (Object) result);
98 }
99
100 public void leave(Node astNode, VirtualFrame frame, int result) {
101 leave(astNode, frame, (Object) result);
102 }
103
104 public void leave(Node astNode, VirtualFrame frame, long result) {
105 leave(astNode, frame, (Object) result);
106 }
107
108 public void leave(Node astNode, VirtualFrame frame, char result) {
109 leave(astNode, frame, (Object) result);
110 }
111
112 public void leave(Node astNode, VirtualFrame frame, float result) {
113 leave(astNode, frame, (Object) result);
114 }
115
116 public void leave(Node astNode, VirtualFrame frame, double result) {
117 leave(astNode, frame, (Object) result);
118 }
119
120 public void leave(Node astNode, VirtualFrame frame, Object result) {
121 }
122
123 public void leaveExceptional(Node astNode, VirtualFrame frame, Exception e) {
124 }
39 125
40 } 126 }