com.oracle.truffle.api.instrument.InstrumentationTool Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of truffle-api Show documentation
Truffle is a multi-language framework for executing dynamic languages that achieves high performance when combined with Graal.
The newest version!
/*
 * 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:
 * 

 * A newly created tool is inert until {@linkplain #install() installed}.
 * An installed tool becomes enabled and immediately begins installing
 * {@linkplain Instrument instrumentation} on subsequently created ASTs and collecting data from
 * those instruments
 * A tool may only be installed once.
 * 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.
 * Once installed, a tool can be {@linkplain #setEnabled(boolean) enabled and disabled}
 * arbitrarily.
 * A disabled tool:
 * 
 * Collects no data;
 * Retains existing AST instrumentation;
 * Continues to instrument newly created ASTs; and
 * Retains previously collected data.
 * 
 * 
 * An installed tool may be {@linkplain #reset() reset} at any time, which leaves the tool
 * installed but with all previously collected data removed.
 * A {@linkplain #dispose() disposed} tool removes all instrumentation (but not
 * {@linkplain Probe probes}) and becomes permanently disabled; previously collected data persists.
 * 
 * 
 * Tool-specific methods that access data collected by the tool should:
 * 

 * Return modification-safe representations of the data; and
 * Not change the state of the data.
 * 
 * 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");
        }
    }

}