Mercurial > hg > graal-jvmci-8
comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java @ 19186:3d2296dbace9
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 } |