Mercurial > hg > truffle
comparison truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/package-info.java @ 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 | 11e0412c5b0e |
children | c1c9c6d79f40 |
comparison
equal
deleted
inserted
replaced
22234:959f658b918d | 22235:e110ab9f91fe |
---|---|
22 * or visit www.oracle.com if you need additional information or have any | 22 * or visit www.oracle.com if you need additional information or have any |
23 * questions. | 23 * questions. |
24 */ | 24 */ |
25 | 25 |
26 /** | 26 /** |
27 * Advanced node manipulation instruments. | 27 * <h4>The Truffle Instrumentation Framework</h4> |
28 * <p> | |
29 * This framework permits client | |
30 * {@linkplain com.oracle.truffle.api.iknstrument.Instrumenter.Tool tools}, | |
31 * either builtin or third-party, to observe with <em>very low overhead</em> the execution of a | |
32 * {@linkplain com.oracle.truffle.api.TruffleLanguage Truffle Language} program at the level of | |
33 * <em>AST execution events</em>: | |
34 * <ul> | |
35 * <li>a Truffle | |
36 * {@linkplain com.oracle.truffle.api.nodes.Node Node} is about to be executed, or</li> | |
37 * <li>a Truffle | |
38 * {@linkplain com.oracle.truffle.api.nodes.Node Node} execution has just completed.</li> | |
39 * </ul> | |
40 * The framework supports many kinds of tools, for example simple collectors of data such as | |
41 * {@linkplain com.oracle.truffle.tools.CoverageTracker code coverage}. | |
42 * It also supports Truffle's built-in | |
43 * {@linkplain com.oracle.truffle.api.debug.Debugger debugging services}, as well as utilities | |
44 * that maintain {@linkplain com.oracle.truffle.tools.LineToProbesMap maps of source code locations} | |
45 * for other tools such as {@linkplain com.oracle.truffle.api.debug.Debugger debugging}. | |
46 * | |
47 * <h4>Instrumentation Services</h4> | |
48 * <p> | |
49 * API access to instrumentation services is provided by the | |
50 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter Instrumenter} that is part of | |
51 * the Truffle execution environment. These services fall into several categories: | |
52 * | |
53 * <ul> | |
54 * | |
55 * <li><strong>AST Markup: probing</strong> | |
56 * <ul> | |
57 * <li>Execution events can only be observed at AST locations that have been | |
58 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#probe(com.oracle.truffle.api.nodes.Node) probed}, | |
59 * which results in the creation of a | |
60 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} that is permanently associated with a | |
61 * particular segment of source code, e.g. a "statement", that corresponds to an AST location.</li> | |
62 * <li>Probing is only supported at | |
63 * {@linkplain com.oracle.truffle.api.nodes.Node Nodes} that are implemented to be | |
64 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#isInstrumentable(com.oracle.truffle.api.nodes.Node) | |
65 * instrumentable}.</li> | |
66 * <li>The relationship between a | |
67 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} and | |
68 * a source code location persists across Truffle <em>cloning</em> of ASTs, which is to say, a single | |
69 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} corresponds to (and keeps track of) | |
70 * the equivalent location in every clone of the original AST.</li> | |
71 * <li>Probing is specified by | |
72 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#registerASTProber(ASTProber) registering} | |
73 * an instance of | |
74 * {@linkplain com.oracle.truffle.api.instrument.ASTProber ASTProber}. | |
75 * A default prober provided by each {@linkplain com.oracle.truffle.api.TruffleLanguage TruffelLanguage} | |
76 * will be registered automatically.</li> | |
77 * <li>All AST probing must be complete before any AST execution has started.</li> | |
78 * </ul></li> | |
79 * | |
80 * <li><strong>AST Markup: tagging</strong> | |
81 * <ul> | |
82 * <li>Additional information can be added at any time to a | |
83 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} by | |
84 * {@linkplain com.oracle.truffle.api.instrument.Probe#tagAs(SyntaxTag, Object) adding} to its set of | |
85 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tags}.</li> | |
86 * | |
87 * <li>{@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag Standard tags} should | |
88 * be used for common, language-agnostic concepts such as | |
89 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag#STATEMENT STATEMENT}, and this | |
90 * is usually done by each language's default | |
91 * {@linkplain com.oracle.truffle.api.instrument.ASTProber ASTProber} while | |
92 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes} are being created.</li> | |
93 * <li>{@linkplain com.oracle.truffle.api.instrument.SyntaxTag Tags} serve to configure the behavior | |
94 * of clients during program execution. For example, knowing which | |
95 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes} are on | |
96 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag#STATEMENT STATEMENT nodes} | |
97 * informs both the {@linkplain com.oracle.truffle.tools.CoverageTracker code coverage} counter | |
98 * and the | |
99 * {@linkplain com.oracle.truffle.api.debug.Debugger debugger} while "stepping".</li> | |
100 * <li>{@linkplain com.oracle.truffle.api.instrument.SyntaxTag tags} can also be added at any | |
101 * time by any client for any purpose, including private | |
102 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag Tags} about which other clients | |
103 * can learn nothing.</li> | |
104 * </ul></li> | |
105 * | |
106 * <li><strong>Markup Discovery: finding probes</strong> | |
107 * <ul> | |
108 * <li>Clients can be observe {@linkplain com.oracle.truffle.api.instrument.Probe Probes} | |
109 * being {@linkplain com.oracle.truffle.api.instrument.Instrumenter#probe(com.oracle.truffle.api.nodes.Node) created} and | |
110 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag Tags} being | |
111 * {@linkplain com.oracle.truffle.api.instrument.Probe#tagAs(SyntaxTag, Object) added} by | |
112 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#addProbeListener(ProbeListener) registering a | |
113 * {@linkplain com.oracle.truffle.api.instrument.ProbeListener ProbeListner}.</li> | |
114 * <li>Clients can also | |
115 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#findProbesTaggedAs(SyntaxTag) find} all existing | |
116 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes}, possibly filtering the search by | |
117 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag}.</li> | |
118 * </ul></li> | |
119 * | |
120 * <li><strong>Observing Execution: event listening:</strong> | |
121 * <ul> | |
122 * <li>Clients can be notified of <em>AST execution events</em> by creating one of several kinds of | |
123 * <em>event listener</em> and <em>attaching</em> it to a | |
124 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe}. This creates an | |
125 * {@linkplain com.oracle.truffle.api.instrument.Instrument Instrument} that notifies the listener | |
126 * of every subsequent execution event at the AST location corresponding to the | |
127 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe}.</li> | |
128 * <li>An | |
129 * {@linkplain com.oracle.truffle.api.instrument.Instrument Instrument} can be | |
130 * {@linkplain com.oracle.truffle.api.instrument.Instrument#dispose() disposed}, at which time | |
131 * it is removed from service at every clone of the AST, incurs no further overhead, and is | |
132 * permanently unusable.</li> | |
133 * <li>Many clients need only implement a | |
134 * {@linkplain com.oracle.truffle.api.instrument.SimpleInstrumentListener SimpleInstrumentListener}, | |
135 * whose notification methods provide only the instance of the | |
136 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} to which it was attached. This | |
137 * provides access to the corresponding | |
138 * {@linkplain com.oracle.truffle.api.SourceSection source code location} and any | |
139 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tags} that had been applied there.</li> | |
140 * <li>Clients that require deeper access to execution state implement a | |
141 * {@linkplain com.oracle.truffle.api.instrument.StandardInstrumentListener StandardInstrumentListener} | |
142 * whose notification methods provide access to the concrete | |
143 * {@linkplain com.oracle.truffle.api.nodes.Node AST location} and current | |
144 * {@linkplain com.oracle.truffle.api.frame.Frame stack frame}.</li> | |
145 * <li>Clients can also create an | |
146 * {@linkplain com.oracle.truffle.api.instrument.Instrument Instrument} (whose design is currently | |
147 * under revision) that supports (effectively) inserting a Truffle AST fragment into the AST | |
148 * location, where it will be executed subject to full Truffle optimization.</li> | |
149 * </ul></li> | |
150 * | |
151 * <li><strong>Wide-area Instrumentation: traps</strong> | |
152 * <ul> | |
153 * <li>A specialized form of Instrumentation is provided that efficiently attaches a single | |
154 * listener called a | |
155 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTagTrap tag trap} to every | |
156 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} containing a specified | |
157 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag}.</li> | |
158 * <li>One (but no more than one) | |
159 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTagTrap tag trap} may optionally be set | |
160 * to be notified <em>before</em> every <em>AST execution event</em> where the specified | |
161 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag} is present.</li> | |
162 * <li>One (but no more than one) | |
163 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTagTrap tag trap} may optionally be set | |
164 * to be notified <em>after</em> every <em>AST execution event</em> where the specified | |
165 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTag tag} is present.</li> | |
166 * <li>The | |
167 * {@linkplain com.oracle.truffle.api.instrument.SyntaxTagTrap tag trap} mechanism is independent | |
168 * of listeners that may be attached to | |
169 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe}. It is especially valuable for | |
170 * applications such as the debugger, where during "stepping" the program should be halted at | |
171 * any node tagged with | |
172 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag#STATEMENT STATEMENT}.</li> | |
173 * </ul></li> | |
174 * | |
175 * <li><strong>Data Gathering Utilities: tools</strong> | |
176 * <ul> | |
177 * <li>The Instrumentation Framework supports extensible set of utilities that can be | |
178 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter#install(com.oracle.truffle.api.instrument.Instrumenter.Tool) | |
179 * installed}, at which time they start collecting information that can be queried at any time.</li> | |
180 * <li>Once installed, these | |
181 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter.Tool tools} can be dynamically | |
182 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter.Tool#setEnabled(boolean) disabled and re-enabled} and eventually | |
183 * {@linkplain com.oracle.truffle.api.instrument.Instrumenter.Tool#dispose() disposed} when no longer needed.</li> | |
184 * <li>A useful example is the | |
185 * {@linkplain com.oracle.truffle.tools.LineToProbesMap LineToProbesMap}, which incrementally builds and maintains a map of | |
186 * {@linkplain com.oracle.truffle.api.instrument.Probe Probes} indexed by | |
187 * {@linkplain com.oracle.truffle.api.source.LineLocation source code line}. Truffle | |
188 * {@linkplain com.oracle.truffle.api.debug.Debugger debugging services} depend heavily on this utility.</li> | |
189 * <li>The | |
190 * {@linkplain com.oracle.truffle.tools.CoverageTracker CoverageTracker} maintains counts of execution events where a | |
191 * {@linkplain com.oracle.truffle.api.instrument.Probe Probe} has been tagged with | |
192 * {@linkplain com.oracle.truffle.api.instrument.StandardSyntaxTag#STATEMENT STATEMENT}, indexed by source code line.</li> | |
193 * </ul></li> | |
194 * </ul> | |
195 * | |
28 */ | 196 */ |
29 package com.oracle.truffle.api.instrument; | 197 package com.oracle.truffle.api.instrument; |
30 | 198 |