Mercurial > hg > graal-compiler

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ProbeNode.java @ 18985:867058575979

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle: Improved support for "probing" AST nodes: - Node.isSafelyReplacaeableBy(Node) checks in advance if Node.replace(Node) would be unsafe (crash the VM). - Hoist Probe() from language imlementations into Node; now completely language agnostic. - Language implementations support probing by implementing Node.isInstrumentable() and Node.createWrapperNode() - Node.Probe() throws ProbeException (without side effects) if the probe fails. -- ProbeException contains an instance of ProbeFailure that diagnoses the failure in detail - Additional measures to prevent instrumentation from being applied to internal InstrumentationNodes. - Promote ProbeListener to top level interface and add a default implementation
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Tue, 27 Jan 2015 20:24:54 -0800
parents e3c95cbbb50c
children 128586040207
comparison
equal deleted inserted replaced
18984:0f462015296f 18985:867058575979
1 /* 1 /*
2 * Copyright (c) 2013, 2014, Oracle and/or its affiliates. All rights reserved. 2 * Copyright (c) 2013, 2015, 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
36 * Implementation interfaces and classes for attaching {@link Probe}s to {@link WrapperNode}s. 36 * Implementation interfaces and classes for attaching {@link Probe}s to {@link WrapperNode}s.
37 */ 37 */
38 public abstract class ProbeNode extends Node implements TruffleEventReceiver, InstrumentationNode { 38 public abstract class ProbeNode extends Node implements TruffleEventReceiver, InstrumentationNode {
39 39
40 /** 40 /**
41 * Any Truffle node implementing this interface can be "instrumented" by installing a 41 * A node that can be inserted into a Truffle AST, and which enables {@linkplain Instrument
42 * {@link Probe} that intercepts execution events at the node and routes them to any 42 * instrumentation} at a particular Guest Language (GL) node. Implementations must extend
43 * {@link Instrument}s that have been attached to the {@link Probe}. Only one {@link Probe} may 43 * {@link Node} and should override {@link Node#isInstrumentable()} to return {@code false}.
44 * be installed at each node; subsequent calls return the one already installed.
45 *
46 * @see Instrument
47 */
48 public interface Instrumentable {
49
50 /**
51 * Enables "instrumentation" of a Guest Language Truffle node, where the node is presumed to
52 * be part of a well-formed Truffle AST that is not being executed. The AST may be modified
53 * as a side effect.
54 * <p>
55 * This interface is not intended to be visible as part of the API for tools
56 * (instrumentation clients).
57 *
58 * @return a (possibly newly created) {@link Probe} associated with this node.
59 */
60 Probe probe();
61
62 /**
63 * Enables a one-time, unchangeable "instrumentation" of a Guest Language Truffle node,
64 * where the node is presumed to be part of a well-formed Truffle AST that is not being
65 * executed. The AST may be modified as a side-effect. Unlike {@link #probe()}, once
66 * {@link #probeLite(TruffleEventReceiver)} is called at a node, no additional probing can
67 * be added and no additional instrumentation can be attached.
68 * <p>
69 * This interface is not intended to be visible as part of the API for tools
70 * (instrumentation clients).
71 *
72 * @param eventReceiver The {@link TruffleEventReceiver} for the single "instrument" being
73 * attached to this node.
74 */
75 void probeLite(TruffleEventReceiver eventReceiver);
76 }
77
78 /**
79 * A node that can be inserted into a Truffle AST, and which enables <em>instrumentation</em> at
80 * a particular Guest Language (GL) node.
81 * <p> 44 * <p>
82 * The implementation must be GL-specific. A wrapper <em>decorates</em> a GL AST node (the 45 * The implementation must be GL-specific. A wrapper <em>decorates</em> a GL AST node (the
83 * wrapper's <em>child</em>) by acting as a transparent <em>proxy</em> with respect to the GL's 46 * wrapper's <em>child</em>) by acting as a transparent <em>proxy</em> with respect to the GL's
84 * execution semantics. 47 * execution semantics.
85 * <p> 48 * <p>
113 * {@code this.probeNode=insert(newProbeNode);}</li> 76 * {@code this.probeNode=insert(newProbeNode);}</li>
114 * <li>Most importantly, Wrappers must be implemented so that Truffle optimization will reduce 77 * <li>Most importantly, Wrappers must be implemented so that Truffle optimization will reduce
115 * their runtime overhead to zero when there are no attached {@link Instrument}s.</li> 78 * their runtime overhead to zero when there are no attached {@link Instrument}s.</li>
116 * </ol> 79 * </ol>
117 * <p> 80 * <p>
118 * <strong>Disclaimer:</strong> experimental interface under development.
119 * 81 *
120 * @see Instrument 82 * @see Instrument
121 */ 83 */
122 public interface WrapperNode extends InstrumentationNode { 84 public interface WrapperNode extends InstrumentationNode {
123 85
128 */ 90 */
129 Node getChild(); 91 Node getChild();
130 92
131 /** 93 /**
132 * Gets the {@link Probe} responsible for installing this wrapper; none if the wrapper 94 * Gets the {@link Probe} responsible for installing this wrapper; none if the wrapper
133 * installed via {@linkplain Instrumentable#probeLite(TruffleEventReceiver) "lite-Probing"}. 95 * installed via {@linkplain Node#probeLite(TruffleEventReceiver) "lite-Probing"}.
134 */ 96 */
135 Probe getProbe(); 97 Probe getProbe();
136 98
137 /** 99 /**
138 * Implementation support for completing a newly created wrapper node. 100 * Implementation support for completing a newly created wrapper node.
159 * specific instance of {@link WrapperNode}. 121 * specific instance of {@link WrapperNode}.
160 */ 122 */
161 public static void insertProbeLite(WrapperNode wrapper, TruffleEventReceiver eventReceiver) { 123 public static void insertProbeLite(WrapperNode wrapper, TruffleEventReceiver eventReceiver) {
162 final ProbeLiteNode probeLiteNode = new ProbeLiteNode(eventReceiver); 124 final ProbeLiteNode probeLiteNode = new ProbeLiteNode(eventReceiver);
163 wrapper.insertProbe(probeLiteNode); 125 wrapper.insertProbe(probeLiteNode);
126 }
127
128 @Override
129 public boolean isInstrumentable() {
130 return false;
164 } 131 }
165 132
166 /** 133 /**
167 * @return the {@link Probe} permanently associated with this {@link ProbeNode}. 134 * @return the {@link Probe} permanently associated with this {@link ProbeNode}.
168 * 135 *