# HG changeset patch # User Michael Van De Vanter # Date 1423454740 28800 # Node ID 3d2296dbace988caaa96a1a46f50e0f323f1401b # Parent 98967b613c886a3e4aff6e936af27a3cc7a030f9 Truffle/Instrumentation: TruffleTool renamed to InstrumentationTool (the base class for a group of tools that collect information during program execution) diff -r 98967b613c88 -r 3d2296dbace9 graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/tools/TruffleToolTest.java --- a/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/tools/TruffleToolTest.java Sat Feb 07 02:47:00 2015 +0100 +++ b/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/tools/TruffleToolTest.java Sun Feb 08 20:05:40 2015 -0800 @@ -29,7 +29,7 @@ import com.oracle.truffle.api.instrument.*; /** - * Test the basic life cycle properties shared by all instances of {@link TruffleTool}. + * Test the basic life cycle properties shared by all instances of {@link InstrumentationTool}. */ public class TruffleToolTest { @@ -110,7 +110,7 @@ tool.dispose(); } - private static final class DummyTruffleTool extends TruffleTool { + private static final class DummyTruffleTool extends InstrumentationTool { @Override protected boolean internalInstall() { diff -r 98967b613c88 -r 3d2296dbace9 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java Sun Feb 08 20:05:40 2015 -0800 @@ -0,0 +1,185 @@ +/* + * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ +package com.oracle.truffle.api.instrument; + +/** + * {@linkplain Instrument Instrumentation}-based tools that gather data during Guest Language + * program execution. + *

+ * Tools share a common life cycle: + *

+ *

+ * Tool-specific methods that access data collected by the tool should: + *

+ * Note:
+ * Tool installation is currently global to the Truffle Execution environment. When + * language-agnostic management of individual execution environments is added to the platform, + * installation will be (optionally) specific to a single execution environment. + */ +public abstract class InstrumentationTool { + // TODO (mlvdv) still thinking about the most appropriate name for this class of tools + + private enum ToolState { + + /** Not yet installed, inert. */ + UNINSTALLED, + + /** Installed, collecting data. */ + ENABLED, + + /** Installed, not collecting data. */ + DISABLED, + + /** Was installed, but now removed, inactive, and no longer usable. */ + DISPOSED; + } + + private ToolState toolState = ToolState.UNINSTALLED; + + protected InstrumentationTool() { + } + + /** + * Connect the tool to some part of the Truffle runtime, and enable data collection to start. + * Instrumentation will only be added to subsequently created ASTs. + * + * @throws IllegalStateException if the tool has previously been installed. + */ + public final void install() { + checkUninstalled(); + if (internalInstall()) { + toolState = ToolState.ENABLED; + } + } + + /** + * @return whether the tool is currently collecting data. + */ + public final boolean isEnabled() { + return toolState == ToolState.ENABLED; + } + + /** + * Switches tool state between enabled (collecting data) and disabled (not + * collecting data, but keeping data already collected). + * + * @throws IllegalStateException if not yet installed or disposed. + */ + public final void setEnabled(boolean isEnabled) { + checkInstalled(); + internalSetEnabled(isEnabled); + toolState = isEnabled ? ToolState.ENABLED : ToolState.DISABLED; + } + + /** + * Clears any data already collected, but otherwise does not change the state of the tool. + * + * @throws IllegalStateException if not yet installed or disposed. + */ + public final void reset() { + checkInstalled(); + internalReset(); + } + + /** + * Makes the tool permanently disabled, removes instrumentation, but keeps data already + * collected. + * + * @throws IllegalStateException if not yet installed or disposed. + */ + public final void dispose() { + checkInstalled(); + internalDispose(); + toolState = ToolState.DISPOSED; + } + + /** + * @return whether the installation succeeded. + */ + protected abstract boolean internalInstall(); + + /** + * No subclass action required. + * + * @param isEnabled + */ + protected void internalSetEnabled(boolean isEnabled) { + } + + protected abstract void internalReset(); + + protected abstract void internalDispose(); + + /** + * Ensure that the tool is currently installed. + * + * @throws IllegalStateException + */ + private void checkInstalled() throws IllegalStateException { + if (toolState == ToolState.UNINSTALLED) { + throw new IllegalStateException("Tool " + getClass().getSimpleName() + " not yet installed"); + } + if (toolState == ToolState.DISPOSED) { + throw new IllegalStateException("Tool " + getClass().getSimpleName() + " has been disposed"); + } + } + + /** + * Ensure that the tool has not yet been installed. + * + * @throws IllegalStateException + */ + private void checkUninstalled() { + if (toolState != ToolState.UNINSTALLED) { + throw new IllegalStateException("Tool " + getClass().getSimpleName() + " has already been installed"); + } + } + +} diff -r 98967b613c88 -r 3d2296dbace9 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/TruffleTool.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/TruffleTool.java Sat Feb 07 02:47:00 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,184 +0,0 @@ -/* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA - * or visit www.oracle.com if you need additional information or have any - * questions. - */ -package com.oracle.truffle.api.instrument; - -/** - * {@linkplain Instrument Instrumentation}-based tools that gather data during Guest Language - * program execution. - *

- * Tools share a common life cycle: - *

- *

- * Tool-specific methods that access data collected by the tool should: - *

- * Note:
- * Tool installation is currently global to the Truffle Execution environment. When - * language-agnostic management of individual execution environments is added to the platform, - * installation will be (optionally) specific to a single execution environment. - */ -public abstract class TruffleTool { - - private enum ToolState { - - /** Not yet installed, inert. */ - UNINSTALLED, - - /** Installed, collecting data. */ - ENABLED, - - /** Installed, not collecting data. */ - DISABLED, - - /** Was installed, but now removed, inactive, and no longer usable. */ - DISPOSED; - } - - private ToolState toolState = ToolState.UNINSTALLED; - - protected TruffleTool() { - } - - /** - * Connect the tool to some part of the Truffle runtime, and enable data collection to start. - * Instrumentation will only be added to subsequently created ASTs. - * - * @throws IllegalStateException if the tool has previously been installed. - */ - public final void install() { - checkUninstalled(); - if (internalInstall()) { - toolState = ToolState.ENABLED; - } - } - - /** - * @return whether the tool is currently collecting data. - */ - public final boolean isEnabled() { - return toolState == ToolState.ENABLED; - } - - /** - * Switches tool state between enabled (collecting data) and disabled (not - * collecting data, but keeping data already collected). - * - * @throws IllegalStateException if not yet installed or disposed. - */ - public final void setEnabled(boolean isEnabled) { - checkInstalled(); - internalSetEnabled(isEnabled); - toolState = isEnabled ? ToolState.ENABLED : ToolState.DISABLED; - } - - /** - * Clears any data already collected, but otherwise does not change the state of the tool. - * - * @throws IllegalStateException if not yet installed or disposed. - */ - public final void reset() { - checkInstalled(); - internalReset(); - } - - /** - * Makes the tool permanently disabled, removes instrumentation, but keeps data already - * collected. - * - * @throws IllegalStateException if not yet installed or disposed. - */ - public final void dispose() { - checkInstalled(); - internalDispose(); - toolState = ToolState.DISPOSED; - } - - /** - * @return whether the installation succeeded. - */ - protected abstract boolean internalInstall(); - - /** - * No subclass action required. - * - * @param isEnabled - */ - protected void internalSetEnabled(boolean isEnabled) { - } - - protected abstract void internalReset(); - - protected abstract void internalDispose(); - - /** - * Ensure that the tool is currently installed. - * - * @throws IllegalStateException - */ - private void checkInstalled() throws IllegalStateException { - if (toolState == ToolState.UNINSTALLED) { - throw new IllegalStateException("Tool " + getClass().getSimpleName() + " not yet installed"); - } - if (toolState == ToolState.DISPOSED) { - throw new IllegalStateException("Tool " + getClass().getSimpleName() + " has been disposed"); - } - } - - /** - * Ensure that the tool has not yet been installed. - * - * @throws IllegalStateException - */ - private void checkUninstalled() { - if (toolState != ToolState.UNINSTALLED) { - throw new IllegalStateException("Tool " + getClass().getSimpleName() + " has already been installed"); - } - } - -} diff -r 98967b613c88 -r 3d2296dbace9 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/CoverageTracker.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/CoverageTracker.java Sat Feb 07 02:47:00 2015 +0100 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/CoverageTracker.java Sun Feb 08 20:05:40 2015 -0800 @@ -38,7 +38,7 @@ import com.oracle.truffle.api.source.*; /** - * A {@link TruffleTool} that counts interpreter execution calls to AST nodes that hold a + * A {@link InstrumentationTool} that counts interpreter execution calls to AST nodes that hold a * specified {@linkplain SyntaxTag tag}, tabulated by source and line number associated with each * node. Tags are presumed to be applied external to the tool. If no tag is specified, * {@linkplain StandardSyntaxTag#STATEMENT STATEMENT} is used, corresponding to conventional @@ -46,7 +46,7 @@ *

* Tool Life Cycle *

- * See {@link TruffleTool} for the life cycle common to all such tools. + * See {@link InstrumentationTool} for the life cycle common to all such tools. *

* Execution Counts *

@@ -72,7 +72,7 @@ * @see Instrument * @see SyntaxTag */ -public final class CoverageTracker extends TruffleTool { +public final class CoverageTracker extends InstrumentationTool { /** Counting data. */ private final Map counters = new HashMap<>(); diff -r 98967b613c88 -r 3d2296dbace9 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/LineToProbesMap.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/LineToProbesMap.java Sat Feb 07 02:47:00 2015 +0100 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/LineToProbesMap.java Sun Feb 08 20:05:40 2015 -0800 @@ -32,10 +32,10 @@ import com.oracle.truffle.api.source.*; /** - * A {@link TruffleTool} that builds a map of every {@Probe} attached to some AST, indexed + * A {@link InstrumentationTool} that builds a map of every {@Probe} attached to some AST, indexed * by {@link Source} and line number. */ -public final class LineToProbesMap extends TruffleTool { +public final class LineToProbesMap extends InstrumentationTool { private static final boolean TRACE = false; private static final PrintStream OUT = System.out; diff -r 98967b613c88 -r 3d2296dbace9 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/NodeExecCounter.java --- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/NodeExecCounter.java Sat Feb 07 02:47:00 2015 +0100 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/NodeExecCounter.java Sun Feb 08 20:05:40 2015 -0800 @@ -36,13 +36,13 @@ import com.oracle.truffle.api.nodes.Node.Child; /** - * A {@link TruffleTool} that counts interpreter execution calls to AST nodes, tabulated by + * A {@link InstrumentationTool} that counts interpreter execution calls to AST nodes, tabulated by * the type of called nodes; counting can be enabled all nodes or restricted to nodes with * a specified {@linkplain SyntaxTag tag} that is presumed to be applied external to the tool. *

* Tool Life Cycle *

- * See {@link TruffleTool} for the life cycle common to all such tools. + * See {@link InstrumentationTool} for the life cycle common to all such tools. *

* Execution Counts *

@@ -79,7 +79,7 @@ * @see SyntaxTag * @see ProbeFailure */ -public final class NodeExecCounter extends TruffleTool { +public final class NodeExecCounter extends InstrumentationTool { /** * Execution count for AST nodes of a particular type.