Mercurial > hg > truffle
changeset 22235:e110ab9f91fe
Truffle/Instrumentation: package-info for com.oracle.truffle.api.instrument
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Mon, 21 Sep 2015 21:21:29 -0700 |
parents | 959f658b918d |
children | df222c4e9bd9 |
files | truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/package-info.java |
diffstat | 1 files changed, 169 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/package-info.java Mon Sep 21 17:03:27 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/package-info.java Mon Sep 21 21:21:29 2015 -0700 @@ -24,7 +24,175 @@ */ /** - * Advanced node manipulation instruments. + * <h4>The Truffle Instrumentation Framework</h4> + * <p> + * This framework permits client + * {@linkplain com.oracle.truffle.api.iknstrument.Instrumenter.Tool tools}, + * either builtin or third-party, to observe with <em>very low overhead</em> the execution of a + * {@linkplain com.oracle.truffle.api.TruffleLanguage Truffle Language} program at the level of + * <em>AST execution events</em>: + * <ul> + * <li>a Truffle + * {@linkplain com.oracle.truffle.api.nodes.Node Node} is about to be executed, or</li> + * <li>a Truffle + * {@linkplain com.oracle.truffle.api.nodes.Node Node} execution has just completed.</li> + * </ul> + * The framework supports many kinds of tools, for example simple collectors of data such as + * {@linkplain com.oracle.truffle.tools.CoverageTracker code coverage}. + * 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.tools.LineToProbesMap maps of source code locations} + * for other tools such as {@linkplain com.oracle.truffle.api.debug.Debugger debugging}. + * + * <h4>Instrumentation Services</h4> + * <p> + * 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: + * + * <ul> + * + * <li><strong>AST Markup: probing</strong> + * <ul> + * <li>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.</li> + * <li>Probing is only supported at + * {@linkplain com.oracle.truffle.api.nodes.Node Nodes} that are implemented to be + * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#isInstrumentable(com.oracle.truffle.api.nodes.Node) + * instrumentable}.</li> + * <li>The relationship between a + * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} and + * a source code location persists across Truffle <em>cloning</em> 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.</li> + * <li>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.</li> + * <li>All AST probing must be complete before any AST execution has started.</li> + * </ul></li> + * + * <li><strong>AST Markup: tagging</strong> + * <ul> + * <li>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}.</li> + * + * <li>{@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.</li> + * <li>{@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 {@linkplain com.oracle.truffle.tools.CoverageTracker code coverage} counter + * and the + * {@linkplain com.oracle.truffle.api.debug.Debugger debugger} while "stepping".</li> + * <li>{@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.</li> + * </ul></li> + * + * <li><strong>Markup Discovery: finding probes</strong> + * <ul> + * <li>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 ProbeListner}.</li> + * <li>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}.</li> + * </ul></li> + * + * <li><strong>Observing Execution: event listening:</strong> + * <ul> + * <li>Clients can be notified of <em>AST execution events</em> by creating one of several kinds of + * <em>event listener</em> and <em>attaching</em> it to a + * {@linkplain com.oracle.truffle.api.instrument.Probe Probe}. This creates an + * {@linkplain com.oracle.truffle.api.instrument.Instrument 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}.</li> + * <li>An + * {@linkplain com.oracle.truffle.api.instrument.Instrument Instrument} can be + * {@linkplain com.oracle.truffle.api.instrument.Instrument#dispose() disposed}, at which time + * it is removed from service at every clone of the AST, incurs no further overhead, and is + * permanently unusable.</li> + * <li>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.SourceSection source code location} and any + * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tags} that had been applied there.</li> + * <li>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}.</li> + * <li>Clients can also create an + * {@linkplain com.oracle.truffle.api.instrument.Instrument 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.</li> + * </ul></li> + * + * <li><strong>Wide-area Instrumentation: traps</strong> + * <ul> + * <li>A specialized form of Instrumentation is provided that efficiently attaches a single + * listener called a + * {@linkplain com.oracle.truffle.api.instrument.SyntaxTagTrap tag trap} to every + * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} containing a specified + * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag}.</li> + * <li>One (but no more than one) + * {@linkplain com.oracle.truffle.api.instrument.SyntaxTagTrap tag trap} may optionally be set + * to be notified <em>before</em> every <em>AST execution event</em> where the specified + * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag} is present.</li> + * <li>One (but no more than one) + * {@linkplain com.oracle.truffle.api.instrument.SyntaxTagTrap tag trap} may optionally be set + * to be notified <em>after</em> every <em>AST execution event</em> where the specified + * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag} is present.</li> + * <li>The + * {@linkplain com.oracle.truffle.api.instrument.SyntaxTagTrap tag trap} mechanism is independent + * of listeners that may be attached to + * {@linkplain com.oracle.truffle.api.instrument.Probe Probe}. 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}.</li> + * </ul></li> + * + * <li><strong>Data Gathering Utilities: tools</strong> + * <ul> + * <li>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.</li> + * <li>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.</li> + * <li>A useful example is the + * {@linkplain com.oracle.truffle.tools.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.</li> + * <li>The + * {@linkplain com.oracle.truffle.tools.CoverageTracker 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.</li> + * </ul></li> + * </ul> + * */ package com.oracle.truffle.api.instrument;