Mercurial > hg > graal-compiler

annotate graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Wrapper.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 50d79ad439f1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
15279
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
1 /*
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
2 * Copyright (c) 2013, 2014, Oracle and/or its affiliates. All rights reserved.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
4 *
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
7 * published by the Free Software Foundation. Oracle designates this
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
8 * particular file as subject to the "Classpath" exception as provided
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
9 * by Oracle in the LICENSE file that accompanied this code.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
10 *
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
15 * accompanied this code).
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
16 *
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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,
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
20 *
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
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
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
23 * questions.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
24 */
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
25 package com.oracle.truffle.api.instrument;
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
26
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
27 import com.oracle.truffle.api.nodes.*;
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
28
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
29 /**
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
30 * A node that can be inserted into a Truffle AST in order to attach <em>instrumentation</em> at a
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
31 * particular node.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
32 * <p>
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
33 * A wrapper <em>decorates</em> an AST node (its <em>child</em>) by acting as a transparent
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
34 * <em>proxy</em> for the child with respect to Truffle execution semantics.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
35 * <p>
15605
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
36 * A wrapper is also expected to notify its associated {@link Probe} when {@link ExecutionEvents}
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
37 * occur at the wrapper during program execution.
15279
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
38 * <p>
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
39 * The wrapper's {@link Probe} is shared by every copy of the wrapper made when the AST is copied.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
40 * <p>
15605
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
41 * Wrapper implementation guidelines:
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
42 * <ol>
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
43 * <li>Every guest language implementation should include a Wrapper implementation; usually only one
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
44 * is needed.</li>
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
45 * <li>The Wrapper type should descend from the <em>language-specific node class</em> of the guest
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
46 * language.</li>
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
47 * <li>The Wrapper must have a single {@code @Child private <guestLanguage>Node child} field.</li>
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
48 * <li>The Wrapper must act as a <em>proxy</em> for its child, which means implementing every
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
49 * possible <em>execute-</em> method that gets called on guest language AST node types by their
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
50 * parents, and passing along each call to its child.</li>
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
51 * <li>The Wrapper must have a single {@code private final Probe probe} to which an optional probe
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
52 * can be attached during node construction.</li>
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
53 * <li>Wrapper methods must also notify its attached {@link Probe}, if any, in terms of standard
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
54 * {@link ExecutionEvents}.</li>
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
55 * <li>Most importantly, Wrappers must be implemented so that Truffle optimization will reduce their
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
56 * runtime overhead to zero when there is no probe attached or when a probe has no attached
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
57 * {@link Instrument}s.</li>
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
58 * </ol>
15279
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
59 * <p>
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
60 * <strong>Disclaimer:</strong> experimental interface under development.
15605
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
61 *
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
62 * @see Probe
bb9473723904 Truffle/Instrumentation:
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 15279
diff changeset
63 * @see ExecutionEvents
15279
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
64 */
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
65 public interface Wrapper extends PhylumTagged {
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
66
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
67 /**
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
68 * Gets the AST node being instrumented, which should never be an instance of {@link Wrapper}.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
69 */
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
70 Node getChild();
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
71
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
72 /**
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
73 * Gets the {@link Probe} to which events occurring at this wrapper's child are propagated.
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
74 */
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
75 Probe getProbe();
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
76
0c6d8a08e31b Truffle: Major cleanup and extension of the Truffle Instrumentation framework in com.oracle.truffle.api
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
77 }