Mercurial > hg > graal-jvmci-8

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java @ 19186:3d2296dbace9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: TruffleTool renamed to InstrumentationTool (the base class for a group of tools that collect information during program execution)
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Sun, 08 Feb 2015 20:05:40 -0800
parents graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/TruffleTool.java@c7e57dffc5ad
children
comparison
equal deleted inserted replaced
19185:98967b613c88 19186:3d2296dbace9
1 /*
2 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
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
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package com.oracle.truffle.api.instrument;
26
27 /**
28 * {@linkplain Instrument Instrumentation}-based tools that gather data during Guest Language
29 * program execution.
30 * <p>
31 * Tools share a common <em>life cycle</em>:
32 * <ul>
33 * <li>A newly created tool is inert until {@linkplain #install() installed}.</li>
34 * <li>An installed tool becomes <em>enabled</em> and immediately begins installing
35 * {@linkplain Instrument instrumentation} on subsequently created ASTs and collecting data from
36 * those instruments</li>
37 * <li>A tool may only be installed once.</li>
38 * <li>It should be possible to install multiple instances of a tool, possibly (but not necessarily)
39 * configured differently with respect to what data is being collected.</li>
40 * <li>Once installed, a tool can be {@linkplain #setEnabled(boolean) enabled and disabled}
41 * arbitrarily.</li>
42 * <li>A disabled tool:
43 * <ul>
44 * <li>Collects no data;</li>
45 * <li>Retains existing AST instrumentation;</li>
46 * <li>Continues to instrument newly created ASTs; and</li>
47 * <li>Retains previously collected data.</li>
48 * </ul>
49 * </li>
50 * <li>An installed tool may be {@linkplain #reset() reset} at any time, which leaves the tool
51 * installed but with all previously collected data removed.</li>
52 * <li>A {@linkplain #dispose() disposed} tool removes all instrumentation (but not
53 * {@linkplain Probe probes}) and becomes permanently disabled; previously collected data persists.</li>
54 * </ul>
55 * <p>
56 * Tool-specific methods that access data collected by the tool should:
57 * <ul>
58 * <li>Return modification-safe representations of the data; and</li>
59 * <li>Not change the state of the data.</li>
60 * </ul>
61 * <b>Note:</b><br>
62 * Tool installation is currently <em>global</em> to the Truffle Execution environment. When
63 * language-agnostic management of individual execution environments is added to the platform,
64 * installation will be (optionally) specific to a single execution environment.
65 */
66 public abstract class InstrumentationTool {
67 // TODO (mlvdv) still thinking about the most appropriate name for this class of tools
68
69 private enum ToolState {
70
71 /** Not yet installed, inert. */
72 UNINSTALLED,
73
74 /** Installed, collecting data. */
75 ENABLED,
76
77 /** Installed, not collecting data. */
78 DISABLED,
79
80 /** Was installed, but now removed, inactive, and no longer usable. */
81 DISPOSED;
82 }
83
84 private ToolState toolState = ToolState.UNINSTALLED;
85
86 protected InstrumentationTool() {
87 }
88
89 /**
90 * Connect the tool to some part of the Truffle runtime, and enable data collection to start.
91 * Instrumentation will only be added to subsequently created ASTs.
92 *
93 * @throws IllegalStateException if the tool has previously been installed.
94 */
95 public final void install() {
96 checkUninstalled();
97 if (internalInstall()) {
98 toolState = ToolState.ENABLED;
99 }
100 }
101
102 /**
103 * @return whether the tool is currently collecting data.
104 */
105 public final boolean isEnabled() {
106 return toolState == ToolState.ENABLED;
107 }
108
109 /**
110 * Switches tool state between <em>enabled</em> (collecting data) and <em>disabled</em> (not
111 * collecting data, but keeping data already collected).
112 *
113 * @throws IllegalStateException if not yet installed or disposed.
114 */
115 public final void setEnabled(boolean isEnabled) {
116 checkInstalled();
117 internalSetEnabled(isEnabled);
118 toolState = isEnabled ? ToolState.ENABLED : ToolState.DISABLED;
119 }
120
121 /**
122 * Clears any data already collected, but otherwise does not change the state of the tool.
123 *
124 * @throws IllegalStateException if not yet installed or disposed.
125 */
126 public final void reset() {
127 checkInstalled();
128 internalReset();
129 }
130
131 /**
132 * Makes the tool permanently <em>disabled</em>, removes instrumentation, but keeps data already
133 * collected.
134 *
135 * @throws IllegalStateException if not yet installed or disposed.
136 */
137 public final void dispose() {
138 checkInstalled();
139 internalDispose();
140 toolState = ToolState.DISPOSED;
141 }
142
143 /**
144 * @return whether the installation succeeded.
145 */
146 protected abstract boolean internalInstall();
147
148 /**
149 * No subclass action required.
150 *
151 * @param isEnabled
152 */
153 protected void internalSetEnabled(boolean isEnabled) {
154 }
155
156 protected abstract void internalReset();
157
158 protected abstract void internalDispose();
159
160 /**
161 * Ensure that the tool is currently installed.
162 *
163 * @throws IllegalStateException
164 */
165 private void checkInstalled() throws IllegalStateException {
166 if (toolState == ToolState.UNINSTALLED) {
167 throw new IllegalStateException("Tool " + getClass().getSimpleName() + " not yet installed");
168 }
169 if (toolState == ToolState.DISPOSED) {
170 throw new IllegalStateException("Tool " + getClass().getSimpleName() + " has been disposed");
171 }
172 }
173
174 /**
175 * Ensure that the tool has not yet been installed.
176 *
177 * @throws IllegalStateException
178 */
179 private void checkUninstalled() {
180 if (toolState != ToolState.UNINSTALLED) {
181 throw new IllegalStateException("Tool " + getClass().getSimpleName() + " has already been installed");
182 }
183 }
184
185 }