Mercurial > hg > graal-jvmci-8
view graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationTool.java @ 19521:b5467bb34b24
Truffle/Instrumentation: some variable renaming for clarity
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Thu, 19 Feb 2015 11:42:03 -0800 |
parents | 3d2296dbace9 |
children |
line wrap: on
line source
/* * 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"); } } }