Mercurial > hg > truffle

changeset 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 98967b613c88
children c5b20395a8bf
files graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/tools/TruffleToolTest.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/TruffleTool.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/CoverageTracker.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/LineToProbesMap.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/NodeExecCounter.java
diffstat 6 files changed, 195 insertions(+), 194 deletions(-) [+]
line wrap: on
line diff
--- 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() {
--- /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.
+ * <p>
+ * Tools share a common <em>life cycle</em>:
+ * <ul>
+ * <li>A newly created tool is inert until {@linkplain #install() installed}.</li>
+ * <li>An installed tool becomes <em>enabled</em> and immediately begins installing
+ * {@linkplain Instrument instrumentation} on subsequently created ASTs and collecting data from
+ * those instruments</li>
+ * <li>A tool may only be installed once.</li>
+ * <li>It should be possible to install multiple instances of a tool, possibly (but not necessarily)
+ * configured differently with respect to what data is being collected.</li>
+ * <li>Once installed, a tool can be {@linkplain #setEnabled(boolean) enabled and disabled}
+ * arbitrarily.</li>
+ * <li>A disabled tool:
+ * <ul>
+ * <li>Collects no data;</li>
+ * <li>Retains existing AST instrumentation;</li>
+ * <li>Continues to instrument newly created ASTs; and</li>
+ * <li>Retains previously collected data.</li>
+ * </ul>
+ * </li>
+ * <li>An installed tool may be {@linkplain #reset() reset} at any time, which leaves the tool
+ * installed but with all previously collected data removed.</li>
+ * <li>A {@linkplain #dispose() disposed} tool removes all instrumentation (but not
+ * {@linkplain Probe probes}) and becomes permanently disabled; previously collected data persists.</li>
+ * </ul>
+ * <p>
+ * Tool-specific methods that access data collected by the tool should:
+ * <ul>
+ * <li>Return modification-safe representations of the data; and</li>
+ * <li>Not change the state of the data.</li>
+ * </ul>
+ * <b>Note:</b><br>
+ * Tool installation is currently <em>global</em> 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 <em>enabled</em> (collecting data) and <em>disabled</em> (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 <em>disabled</em>, 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");
+        }
+    }
+
+}
--- 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.
- * <p>
- * Tools share a common <em>life cycle</em>:
- * <ul>
- * <li>A newly created tool is inert until {@linkplain #install() installed}.</li>
- * <li>An installed tool becomes <em>enabled</em> and immediately begins installing
- * {@linkplain Instrument instrumentation} on subsequently created ASTs and collecting data from
- * those instruments</li>
- * <li>A tool may only be installed once.</li>
- * <li>It should be possible to install multiple instances of a tool, possibly (but not necessarily)
- * configured differently with respect to what data is being collected.</li>
- * <li>Once installed, a tool can be {@linkplain #setEnabled(boolean) enabled and disabled}
- * arbitrarily.</li>
- * <li>A disabled tool:
- * <ul>
- * <li>Collects no data;</li>
- * <li>Retains existing AST instrumentation;</li>
- * <li>Continues to instrument newly created ASTs; and</li>
- * <li>Retains previously collected data.</li>
- * </ul>
- * </li>
- * <li>An installed tool may be {@linkplain #reset() reset} at any time, which leaves the tool
- * installed but with all previously collected data removed.</li>
- * <li>A {@linkplain #dispose() disposed} tool removes all instrumentation (but not
- * {@linkplain Probe probes}) and becomes permanently disabled; previously collected data persists.</li>
- * </ul>
- * <p>
- * Tool-specific methods that access data collected by the tool should:
- * <ul>
- * <li>Return modification-safe representations of the data; and</li>
- * <li>Not change the state of the data.</li>
- * </ul>
- * <b>Note:</b><br>
- * Tool installation is currently <em>global</em> 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 <em>enabled</em> (collecting data) and <em>disabled</em> (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 <em>disabled</em>, 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");
-        }
-    }
-
-}
--- 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 <em>execution calls</em> to AST nodes that hold a
+ * A {@link InstrumentationTool} that counts interpreter <em>execution calls</em> 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 @@
  * <p>
  * <b>Tool Life Cycle</b>
  * <p>
- * See {@link TruffleTool} for the life cycle common to all such tools.
+ * See {@link InstrumentationTool} for the life cycle common to all such tools.
  * <p>
  * <b>Execution Counts</b>
  * <p>
@@ -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<LineLocation, CoverageCounter> counters = new HashMap<>();
--- 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;
--- 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 <em>execution calls</em> to AST nodes, tabulated by
+ * A {@link InstrumentationTool} that counts interpreter <em>execution calls</em> to AST nodes, tabulated by
  * the type of called nodes; counting can be enabled <em>all</em> nodes or restricted to nodes with
  * a specified {@linkplain SyntaxTag tag} that is presumed to be applied external to the tool.
  * <p>
  * <b>Tool Life Cycle</b>
  * <p>
- * See {@link TruffleTool} for the life cycle common to all such tools.
+ * See {@link InstrumentationTool} for the life cycle common to all such tools.
  * </p>
  * <b>Execution Counts</b>
  * <p>
@@ -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.