Mercurial > hg > graal-jvmci-8
comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ProbeNode.java @ 18985:867058575979
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 * |