com.oracle.truffle.api.instrument.package-info Maven / Gradle / Ivy

Go to download
/*
 * 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.
 */

/*
 @ApiInfo(
 group="Obsolete soon"
 )
 */

/**
 * Truffle {@linkplain com.oracle.truffle.api.instrument.Instrumenter Instrumentation}: access to execution events for Debuggers and other tools.
 * 
 * This framework permits client
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter.Tool tools},
 * either builtin or third-party, to observe with very low overhead the execution of a
 * {@linkplain com.oracle.truffle.api.TruffleLanguage Truffle Language} program at the level of
 * AST execution events:
 * 

 * a Truffle
 * {@linkplain com.oracle.truffle.api.nodes.Node Node} is about to be executed, or
 * a Truffle
 * {@linkplain com.oracle.truffle.api.nodes.Node Node} execution has just completed.
 * 
 * The framework supports many kinds of tools, for example simple collectors of data such as the
 * CoverageTracker.
 * It also supports Truffle's built-in
 * {@linkplain com.oracle.truffle.api.debug.Debugger debugging services}, as well as utilities
 * that maintain {@linkplain com.oracle.truffle.api.debug.LineToProbesMap maps of source code locations}
 * for other tools such as {@linkplain com.oracle.truffle.api.debug.Debugger debugging}.
 *
 * Instrumentation Services
 * 
 * API access to instrumentation services is provided by the
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter Instrumenter} that is part of
 * the Truffle execution environment. These services fall into several categories:
 *
 * 

 *
 * AST Markup: probing
 * 
 * Execution events can only be observed at AST locations that have been
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#probe(com.oracle.truffle.api.nodes.Node) probed},
 * which results in the creation of a
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} that is permanently associated with a
 * particular segment of source code, e.g. a "statement", that corresponds to an AST location.
 * Probing is only supported at
 * {@linkplain com.oracle.truffle.api.nodes.Node Nodes} where supported by specific language implementations.
 * The relationship between a
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} and
 * a source code location persists across Truffle cloning of ASTs, which is to say, a single
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} corresponds to (and keeps track of)
 * the equivalent location in every clone of the original AST.
 * Probing is specified by
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#registerASTProber(ASTProber) registering}
 * an instance of
 * {@linkplain com.oracle.truffle.api.instrument.ASTProber ASTProber}.
 * A default prober provided by each {@linkplain com.oracle.truffle.api.TruffleLanguage TruffelLanguage}
 * will be registered automatically.
 * All AST probing must be complete before any AST execution has started.
 * 
 *
 * AST Markup: tagging
 * 
 * Additional information can be added at any time to a
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} by
 * {@linkplain com.oracle.truffle.api.instrument.Probe#tagAs(SyntaxTag, Object) adding} to its set of
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tags}.
 *
 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag Standard tags} should
 * be used for common, language-agnostic concepts such as
 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag#STATEMENT STATEMENT}, and this
 * is usually done by each language's default
 * {@linkplain com.oracle.truffle.api.instrument.ASTProber ASTProber} while
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes} are being created.
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag Tags} serve to configure the behavior
 * of clients during program execution.  For example, knowing which
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes} are on
 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag#STATEMENT STATEMENT nodes}
 * informs both the CoverageTracker and the
 * {@linkplain com.oracle.truffle.api.debug.Debugger debugger} while "stepping".
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tags} can also be added at any
 * time by any client for any purpose, including private
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag Tags} about which other clients
 * can learn nothing.
 * 
 *
 * Markup Discovery: finding probes
 * 
 * Clients can be observe {@linkplain com.oracle.truffle.api.instrument.Probe Probes}
 * being {@linkplain com.oracle.truffle.api.instrument.Instrumenter#probe(com.oracle.truffle.api.nodes.Node) created} and
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag Tags} being
 * {@linkplain com.oracle.truffle.api.instrument.Probe#tagAs(SyntaxTag, Object) added} by
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#addProbeListener(ProbeListener) registering} a
 * {@linkplain com.oracle.truffle.api.instrument.ProbeListener ProbeListener}.
 * Clients can also
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#findProbesTaggedAs(SyntaxTag) find} all existing
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes}, possibly filtering the search by
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag}.
 * 
 *
 * Observing Execution: event listening:
 * 
 * Clients can be notified of AST execution events by creating one of several kinds of
 * event listener and attaching it to a
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe}. This creates an
 * {@linkplain com.oracle.truffle.api.instrument.ProbeInstrument Instrument} that notifies the listener
 * of every subsequent execution event at the AST location corresponding to the
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe}.
 * An
 * {@linkplain com.oracle.truffle.api.instrument.ProbeInstrument Instrument} can be
 * {@linkplain com.oracle.truffle.api.instrument.ProbeInstrument#dispose() disposed}, at which time
 * it is removed from service at every clone of the AST, incurs no further overhead, and is
 * permanently unusable.
 * Many clients need only implement a
 * {@linkplain com.oracle.truffle.api.instrument.SimpleInstrumentListener SimpleInstrumentListener},
 * whose notification methods provide only the instance of the
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} to which it was attached.  This
 * provides access to the corresponding
 * {@linkplain com.oracle.truffle.api.source.SourceSection source code location} and any
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tags} that had been applied there.
 * Clients that require deeper access to execution state implement a
 * {@linkplain com.oracle.truffle.api.instrument.StandardInstrumentListener StandardInstrumentListener}
 * whose notification methods provide access to the concrete
 * {@linkplain com.oracle.truffle.api.nodes.Node AST location} and current
 * {@linkplain com.oracle.truffle.api.frame.Frame stack frame}.
 * Clients can also create an
 * {@linkplain com.oracle.truffle.api.instrument.ProbeInstrument Instrument} (whose design is currently
 * under revision) that supports (effectively) inserting a Truffle AST fragment into the AST
 * location, where it will be executed subject to full Truffle optimization.
 * 
 *
 * Wide-area Instrumentation: TagInstruments
 * 
 * A specialized form of Instrumentation is provided that efficiently attaches a single
 * listener called a
 * {@linkplain com.oracle.truffle.api.instrument.StandardBeforeInstrumentListener StandardBeforeInstrumentListener} to every
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} containing a specified
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag}.
 * One (but no more than one)
 * {@linkplain com.oracle.truffle.api.instrument.StandardBeforeInstrumentListener StandardBeforeInstrumentListener}
 * may optionally be attached for notification before every AST execution event where the specified
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag} is present.
 * One (but no more than one)
 * {@linkplain com.oracle.truffle.api.instrument.StandardAfterInstrumentListener StandardAfterInstrumentListener}
 * may optionally be attached for notification after every AST execution event where the specified
 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag} is present.
 * The
 * {@linkplain com.oracle.truffle.api.instrument.TagInstrument TagInstrument} mechanism is independent
 * of listeners that may be attached to
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes}.  It is especially valuable for
 * applications such as the debugger, where during "stepping" the program should be halted at
 * any node tagged with
 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag#STATEMENT STATEMENT}.
 * 
 *
 * Data Gathering Utilities:  tools
 * 
 * The Instrumentation Framework supports extensible set of utilities that can be
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#install(com.oracle.truffle.api.instrument.Instrumenter.Tool)
 * installed}, at which time they start collecting information that can be queried at any time.
 * Once installed, these
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter.Tool tools} can be dynamically
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter.Tool#setEnabled(boolean) disabled and re-enabled} and eventually
 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter.Tool#dispose() disposed} when no longer needed.
 * A useful example is the
 * {@linkplain com.oracle.truffle.api.debug.LineToProbesMap LineToProbesMap}, which incrementally builds and maintains a map of
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes} indexed by
 * {@linkplain com.oracle.truffle.api.source.LineLocation source code line}. Truffle
 * {@linkplain com.oracle.truffle.api.debug.Debugger debugging services} depend heavily on this utility.
 * The CoverageTracker maintains counts of execution events where a
 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} has been tagged with
 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag#STATEMENT STATEMENT}, indexed by source code line.
 * 
 * 
 *
 */
package com.oracle.truffle.api.instrument;