Mercurial > hg > truffle

changeset 22231:59e022cee529

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: rename InstrumentationTool (abstract parent for CoverageTracker, LineToProbesMap, etc.) to Instrumenter.Tool, eliminating the need for an Accessor instance.
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Sun, 20 Sep 2015 17:19:59 -0700
parents 3f2052afcb6d
children 526de3af756d
files truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/LineToProbesMap.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/impl/Accessor.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrumenter.java truffle/com.oracle.truffle.tools.test/src/com/oracle/truffle/tools/test/TruffleToolTest.java truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/CoverageTracker.java truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/LineToProbesMap.java truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/NodeExecCounter.java
diffstat 8 files changed, 179 insertions(+), 225 deletions(-) [+]
line wrap: on
line diff
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/LineToProbesMap.java	Sun Sep 20 16:48:50 2015 -0700
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/LineToProbesMap.java	Sun Sep 20 17:19:59 2015 -0700
@@ -31,7 +31,6 @@
 import java.util.HashMap;
 import java.util.Map;
 
-import com.oracle.truffle.api.instrument.InstrumentationTool;
 import com.oracle.truffle.api.instrument.Instrumenter;
 import com.oracle.truffle.api.instrument.Probe;
 import com.oracle.truffle.api.instrument.ProbeListener;
@@ -44,7 +43,7 @@
  * An {@link InstrumentationTool} that builds a map of every {@link Probe} attached to some AST,
  * indexed by {@link Source} and line number.
  */
-final class LineToProbesMap extends InstrumentationTool {
+final class LineToProbesMap extends Instrumenter.Tool {
 
     private static final boolean TRACE = false;
     private static final PrintStream OUT = System.out;
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/impl/Accessor.java	Sun Sep 20 16:48:50 2015 -0700
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/impl/Accessor.java	Sun Sep 20 17:19:59 2015 -0700
@@ -61,7 +61,6 @@
     private static Accessor NODES;
     private static Accessor INTEROP;
     private static Accessor INSTRUMENT;
-    private static Accessor TOOL;
     private static Accessor DEBUG;
     private static final ThreadLocal<Object> CURRENT_VM = new ThreadLocal<>();
 
@@ -178,11 +177,6 @@
                 throw new IllegalStateException();
             }
             DEBUG = this;
-        } else if (this.getClass().getSimpleName().endsWith("Tool")) {
-            if (TOOL != null) {
-                throw new IllegalStateException();
-            }
-            TOOL = this;
         } else {
             if (SPI != null) {
                 throw new IllegalStateException();
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java	Sun Sep 20 16:48:50 2015 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,209 +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;
-
-import com.oracle.truffle.api.impl.Accessor;
-
-/**
- * {@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(Instrumenter) 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;
-
-    private Instrumenter instrumenter;
-
-    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(Instrumenter inst) {
-        checkUninstalled();
-        if (inst != null) {
-            this.instrumenter = inst;
-        }
-        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();
-
-    protected final Instrumenter getInstrumenter() {
-        if (instrumenter == null) {
-            instrumenter = ACCESSOR.getInstrumenter(null);
-        }
-        return instrumenter;
-    }
-
-    /**
-     * 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");
-        }
-    }
-
-    static final class AccessorTool extends Accessor {
-
-        @Override
-        protected Instrumenter getInstrumenter(Object vm) {
-            return super.getInstrumenter(null);
-        }
-    }
-
-    static final AccessorTool ACCESSOR = new AccessorTool();
-
-}
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrumenter.java	Sun Sep 20 16:48:50 2015 -0700
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrumenter.java	Sun Sep 20 17:19:59 2015 -0700
@@ -67,8 +67,181 @@
         return visitor.source;
     }
 
+    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;
+    }
+
+    /**
+     * {@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(Instrumenter) 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 static class Tool {
+        // TODO (mlvdv) still thinking about the most appropriate name for this class of tools
+
+        private ToolState toolState = ToolState.UNINSTALLED;
+
+        private Instrumenter instrumenter;
+
+        protected Tool() {
+        }
+
+        /**
+         * 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(Instrumenter inst) {
+            checkUninstalled();
+            this.instrumenter = inst;
+
+            if (internalInstall()) {
+                toolState = ToolState.ENABLED;
+            }
+            instrumenter.tools.add(this);
+        }
+
+        /**
+         * @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;
+            instrumenter.tools.remove(this);
+        }
+
+        /**
+         * @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();
+
+        protected final Instrumenter getInstrumenter() {
+            return instrumenter;
+        }
+
+        /**
+         * 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");
+            }
+        }
+    }
+
     private final Object vm;
 
+    /** Tools that have been created, but not yet disposed. */
+    private final Set<Tool> tools = Collections.synchronizedSet(new LinkedHashSet<Tool>());
+
     private final Set<ASTProber> astProbers = Collections.synchronizedSet(new LinkedHashSet<ASTProber>());
 
     private final List<ProbeListener> probeListeners = new ArrayList<>();
@@ -395,6 +568,7 @@
         return afterTagTrap;
     }
 
+    // TODO (mlvdv) build this in as a VM event?
     /**
      * Enables instrumentation in a newly created AST by applying all registered instances of
      * {@link ASTProber}.
--- a/truffle/com.oracle.truffle.tools.test/src/com/oracle/truffle/tools/test/TruffleToolTest.java	Sun Sep 20 16:48:50 2015 -0700
+++ b/truffle/com.oracle.truffle.tools.test/src/com/oracle/truffle/tools/test/TruffleToolTest.java	Sun Sep 20 17:19:59 2015 -0700
@@ -31,7 +31,6 @@
 
 import org.junit.Test;
 
-import com.oracle.truffle.api.instrument.InstrumentationTool;
 import com.oracle.truffle.api.instrument.Instrumenter;
 import com.oracle.truffle.api.vm.TruffleVM;
 
@@ -131,7 +130,7 @@
         return instrumenter;
     }
 
-    private static final class DummyTruffleTool extends InstrumentationTool {
+    private static final class DummyTruffleTool extends Instrumenter.Tool {
 
         @Override
         protected boolean internalInstall() {
--- a/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/CoverageTracker.java	Sun Sep 20 16:48:50 2015 -0700
+++ b/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/CoverageTracker.java	Sun Sep 20 17:19:59 2015 -0700
@@ -34,7 +34,6 @@
 import java.util.TreeSet;
 
 import com.oracle.truffle.api.instrument.Instrument;
-import com.oracle.truffle.api.instrument.InstrumentationTool;
 import com.oracle.truffle.api.instrument.Instrumenter;
 import com.oracle.truffle.api.instrument.Probe;
 import com.oracle.truffle.api.instrument.ProbeListener;
@@ -83,7 +82,7 @@
  * @see Instrument
  * @see SyntaxTag
  */
-public final class CoverageTracker extends InstrumentationTool {
+public final class CoverageTracker extends Instrumenter.Tool {
 
     /** Counting data. */
     private final Map<LineLocation, CoverageRecord> coverageMap = new HashMap<>();
--- a/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/LineToProbesMap.java	Sun Sep 20 16:48:50 2015 -0700
+++ b/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/LineToProbesMap.java	Sun Sep 20 17:19:59 2015 -0700
@@ -31,7 +31,6 @@
 import java.util.HashMap;
 import java.util.Map;
 
-import com.oracle.truffle.api.instrument.InstrumentationTool;
 import com.oracle.truffle.api.instrument.Instrumenter;
 import com.oracle.truffle.api.instrument.Probe;
 import com.oracle.truffle.api.instrument.ProbeListener;
@@ -44,7 +43,7 @@
  * An {@link InstrumentationTool} that builds a map of every {@link Probe} attached to some AST,
  * indexed by {@link Source} and line number.
  */
-public final class LineToProbesMap extends InstrumentationTool {
+public final class LineToProbesMap extends Instrumenter.Tool {
 
     private static final boolean TRACE = false;
     private static final PrintStream OUT = System.out;
--- a/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/NodeExecCounter.java	Sun Sep 20 16:48:50 2015 -0700
+++ b/truffle/com.oracle.truffle.tools/src/com/oracle/truffle/tools/NodeExecCounter.java	Sun Sep 20 17:19:59 2015 -0700
@@ -38,7 +38,6 @@
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.instrument.ASTProber;
 import com.oracle.truffle.api.instrument.Instrument;
-import com.oracle.truffle.api.instrument.InstrumentationTool;
 import com.oracle.truffle.api.instrument.Instrumenter;
 import com.oracle.truffle.api.instrument.Probe;
 import com.oracle.truffle.api.instrument.ProbeException;
@@ -97,7 +96,7 @@
  * @see SyntaxTag
  * @see ProbeFailure
  */
-public final class NodeExecCounter extends InstrumentationTool {
+public final class NodeExecCounter extends Instrumenter.Tool {
 
     /**
      * Execution count for AST nodes of a particular type.