Mercurial > hg > truffle

annotate truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java @ 21972:ff6f34159b8a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Providing package-info for most of API packages. Feel free to provide your package-info.java for anything that has API in its name.
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Tue, 23 Jun 2015 12:44:41 +0200
parents 9c8c0937da41
children 3aad794eec0e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
1 /*
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
2 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
4 *
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
7 * published by the Free Software Foundation. Oracle designates this
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
8 * particular file as subject to the "Classpath" exception as provided
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
9 * by Oracle in the LICENSE file that accompanied this code.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
10 *
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
15 * accompanied this code).
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
16 *
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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,
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
20 *
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
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
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
23 * questions.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
24 */
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
25 package com.oracle.truffle.api.instrument;
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
26
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
27 /**
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
28 * {@linkplain Instrument Instrumentation}-based tools that gather data during Guest Language
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
29 * program execution.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
30 * <p>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
31 * Tools share a common <em>life cycle</em>:
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
32 * <ul>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
33 * <li>A newly created tool is inert until {@linkplain #install() installed}.</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
34 * <li>An installed tool becomes <em>enabled</em> and immediately begins installing
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
35 * {@linkplain Instrument instrumentation} on subsequently created ASTs and collecting data from
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
36 * those instruments</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
37 * <li>A tool may only be installed once.</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
38 * <li>It should be possible to install multiple instances of a tool, possibly (but not necessarily)
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
39 * configured differently with respect to what data is being collected.</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
40 * <li>Once installed, a tool can be {@linkplain #setEnabled(boolean) enabled and disabled}
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
41 * arbitrarily.</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
42 * <li>A disabled tool:
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
43 * <ul>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
44 * <li>Collects no data;</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
45 * <li>Retains existing AST instrumentation;</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
46 * <li>Continues to instrument newly created ASTs; and</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
47 * <li>Retains previously collected data.</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
48 * </ul>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
49 * </li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
50 * <li>An installed tool may be {@linkplain #reset() reset} at any time, which leaves the tool
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
51 * installed but with all previously collected data removed.</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
52 * <li>A {@linkplain #dispose() disposed} tool removes all instrumentation (but not
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
53 * {@linkplain Probe probes}) and becomes permanently disabled; previously collected data persists.</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
54 * </ul>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
55 * <p>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
56 * Tool-specific methods that access data collected by the tool should:
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
57 * <ul>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
58 * <li>Return modification-safe representations of the data; and</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
59 * <li>Not change the state of the data.</li>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
60 * </ul>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
61 * <b>Note:</b><br>
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
62 * Tool installation is currently <em>global</em> to the Truffle Execution environment. When
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
63 * language-agnostic management of individual execution environments is added to the platform,
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
64 * installation will be (optionally) specific to a single execution environment.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
65 */
19186
3d2296dbace9 Truffle/Instrumentation: TruffleTool renamed to InstrumentationTool (the base class for a group of tools that collect information during program execution)
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 19038
diff changeset
66 public abstract class InstrumentationTool {
3d2296dbace9 Truffle/Instrumentation: TruffleTool renamed to InstrumentationTool (the base class for a group of tools that collect information during program execution)
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 19038
diff changeset
67 // TODO (mlvdv) still thinking about the most appropriate name for this class of tools
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
68
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
69 private enum ToolState {
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
70
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
71 /** Not yet installed, inert. */
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
72 UNINSTALLED,
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
73
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
74 /** Installed, collecting data. */
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
75 ENABLED,
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
76
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
77 /** Installed, not collecting data. */
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
78 DISABLED,
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
79
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
80 /** Was installed, but now removed, inactive, and no longer usable. */
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
81 DISPOSED;
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
82 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
83
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
84 private ToolState toolState = ToolState.UNINSTALLED;
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
85
19186
3d2296dbace9 Truffle/Instrumentation: TruffleTool renamed to InstrumentationTool (the base class for a group of tools that collect information during program execution)
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 19038
diff changeset
86 protected InstrumentationTool() {
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
87 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
88
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
89 /**
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
90 * Connect the tool to some part of the Truffle runtime, and enable data collection to start.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
91 * Instrumentation will only be added to subsequently created ASTs.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
92 *
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
93 * @throws IllegalStateException if the tool has previously been installed.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
94 */
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
95 public final void install() {
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
96 checkUninstalled();
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
97 if (internalInstall()) {
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
98 toolState = ToolState.ENABLED;
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
99 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
100 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
101
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
102 /**
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
103 * @return whether the tool is currently collecting data.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
104 */
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
105 public final boolean isEnabled() {
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
106 return toolState == ToolState.ENABLED;
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
107 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
108
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
109 /**
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
110 * Switches tool state between <em>enabled</em> (collecting data) and <em>disabled</em> (not
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
111 * collecting data, but keeping data already collected).
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
112 *
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
113 * @throws IllegalStateException if not yet installed or disposed.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
114 */
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
115 public final void setEnabled(boolean isEnabled) {
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
116 checkInstalled();
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
117 internalSetEnabled(isEnabled);
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
118 toolState = isEnabled ? ToolState.ENABLED : ToolState.DISABLED;
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
119 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
120
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
121 /**
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
122 * Clears any data already collected, but otherwise does not change the state of the tool.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
123 *
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
124 * @throws IllegalStateException if not yet installed or disposed.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
125 */
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
126 public final void reset() {
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
127 checkInstalled();
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
128 internalReset();
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
129 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
130
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
131 /**
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
132 * Makes the tool permanently <em>disabled</em>, removes instrumentation, but keeps data already
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
133 * collected.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
134 *
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
135 * @throws IllegalStateException if not yet installed or disposed.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
136 */
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
137 public final void dispose() {
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
138 checkInstalled();
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
139 internalDispose();
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
140 toolState = ToolState.DISPOSED;
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
141 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
142
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
143 /**
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
144 * @return whether the installation succeeded.
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
145 */
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
146 protected abstract boolean internalInstall();
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
147
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
148 /**
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
149 * No subclass action required.
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
150 *
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
151 * @param isEnabled
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
152 */
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
153 protected void internalSetEnabled(boolean isEnabled) {
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
154 }
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
155
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
156 protected abstract void internalReset();
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
157
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
158 protected abstract void internalDispose();
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
159
19038
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
160 /**
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
161 * Ensure that the tool is currently installed.
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
162 *
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
163 * @throws IllegalStateException
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
164 */
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
165 private void checkInstalled() throws IllegalStateException {
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
166 if (toolState == ToolState.UNINSTALLED) {
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
167 throw new IllegalStateException("Tool " + getClass().getSimpleName() + " not yet installed");
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
168 }
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
169 if (toolState == ToolState.DISPOSED) {
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
170 throw new IllegalStateException("Tool " + getClass().getSimpleName() + " has been disposed");
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
171 }
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
172 }
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
173
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
174 /**
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
175 * Ensure that the tool has not yet been installed.
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
176 *
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
177 * @throws IllegalStateException
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
178 */
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
179 private void checkUninstalled() {
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
180 if (toolState != ToolState.UNINSTALLED) {
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
181 throw new IllegalStateException("Tool " + getClass().getSimpleName() + " has already been installed");
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
182 }
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
183 }
c7e57dffc5ad Truffle/Instrumentation: comments and minor code cleanup post-review
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents: 18987
diff changeset
184
18987
ac114ad31cdd Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
Michael Van De Vanter <michael.van.de.vanter@oracle.com>
parents:
diff changeset
185 }