Mercurial > hg > truffle
annotate truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/WrapperNode.java @ 22248:6d328e688339
Truffle/Instrumentation: Javadoc cleanup
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Wed, 23 Sep 2015 21:48:02 -0700 |
parents | c1c9c6d79f40 |
children | e7643754d982 |
rev | line source |
---|---|
22226
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
1 /* |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
2 * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
4 * |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
5 * This code is free software; you can redistribute it and/or modify it |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
6 * under the terms of the GNU General Public License version 2 only, as |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
7 * published by the Free Software Foundation. Oracle designates this |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
8 * particular file as subject to the "Classpath" exception as provided |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
9 * by Oracle in the LICENSE file that accompanied this code. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
10 * |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
11 * This code is distributed in the hope that it will be useful, but WITHOUT |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
14 * version 2 for more details (a copy is included in the LICENSE file that |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
15 * accompanied this code). |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
16 * |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
17 * You should have received a copy of the GNU General Public License version |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
18 * 2 along with this work; if not, write to the Free Software Foundation, |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
20 * |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
22 * or visit www.oracle.com if you need additional information or have any |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
23 * questions. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
24 */ |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
25 package com.oracle.truffle.api.instrument; |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
26 |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
27 import com.oracle.truffle.api.nodes.Node; |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
28 |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
29 /** |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
30 * A {@link Node} instance that must be inserted into a Truffle AST in order to enable |
22247
c1c9c6d79f40
Truffle/Instrumentation: remove method Instrumenter.isInstrumentable()
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
22226
diff
changeset
|
31 * {@linkplain Instrument instrumentation} at a particular Guest Language (GL) node. |
22226
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
32 * <p> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
33 * The implementation must be GL-specific. A wrapper <em>decorates</em> a GL AST node (the wrapper's |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
34 * <em>child</em>) by acting as a transparent <em>proxy</em> with respect to the GL's execution |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
35 * semantics. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
36 * <p> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
37 * Instrumentation at the wrapped node is implemented by an instance of {@link EventHandlerNode} |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
38 * attached as a second child of the {@link WrapperNode}. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
39 * <p> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
40 * A wrapper is obliged to notify its attached {@link EventHandlerNode} when execution events occur |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
41 * at the wrapped AST node during program execution. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
42 * <p> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
43 * When a GL AST is cloned, the {@link WrapperNode}, its {@link EventHandlerNode} and any |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
44 * {@linkplain Instrument instrumentation} are also cloned; they are in effect part of the GL AST. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
45 * An instance of {@link Probe} represents abstractly the instrumentation at a particular location |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
46 * in a GL AST; it tracks all the copies of the Wrapper and attached instrumentation, and acts as a |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
47 * single point of access for tools. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
48 * <p> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
49 * Implementation guidelines: |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
50 * <ol> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
51 * <li>Each GL implementation must implement a WrapperNode implementation for each AST context in |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
52 * which Instrumentation is to be supported.</li> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
53 * <li>The wrapper type should descend from the <em>GL-specific node class</em>.</li> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
54 * <li>Must have a field: {@code @Child private <GL>Node child;}</li> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
55 * <li>Must have a field: {@code @Child private EventHandlerNode eventHandlerNode;}</li> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
56 * <li>The wrapper must act as a <em>proxy</em> for its child, which means implementing every |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
57 * possible <em>execute-</em> method that gets called on guest language AST node types by their |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
58 * parents, and passing along each call to its child.</li> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
59 * <li>Method {@code Probe getProbe()} should be implemented as {@code eventHandlerNode.getProbe();} |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
60 * <li>Method {@code insertProbe(EventHandlerNode)} should be implemented as |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
61 * {@code this.eventHandlerNode=insert(eventHandlerNode);}</li> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
62 * <li>Most importantly, Wrappers must be implemented so that Truffle optimization will reduce their |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
63 * runtime overhead to zero when there are no attached {@link Instrument}s.</li> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
64 * </ol> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
65 * <p> |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
66 * |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
67 * @see Instrument |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
68 */ |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
69 public interface WrapperNode extends InstrumentationNode { |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
70 |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
71 /** |
22248
6d328e688339
Truffle/Instrumentation: Javadoc cleanup
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
22247
diff
changeset
|
72 * Gets the node being "wrapped", i.e. the AST node for which {@linkplain EventHandlerNode |
6d328e688339
Truffle/Instrumentation: Javadoc cleanup
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
22247
diff
changeset
|
73 * execution events} will be reported through the Instrumentation Framework. |
22226
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
74 */ |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
75 Node getChild(); |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
76 |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
77 /** |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
78 * Gets the {@link Probe} responsible for installing this wrapper. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
79 */ |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
80 Probe getProbe(); |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
81 |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
82 /** |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
83 * Implementation support for completing a newly created wrapper node. |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
84 */ |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
85 void insertEventHandlerNode(EventHandlerNode eventHandlerNode); |
c896a8e70777
Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff
changeset
|
86 } |