Mercurial > hg > graal-jvmci-8
comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/CoverageTracker.java @ 18987:ac114ad31cdd
Truffle/Tools: a new framework for pluggable tools that gather Truffle execution data
- Abstract com.oracle.truffle.api.instrument.TruffleTool defines, documents, and enforces a standard "life cycle":
-- includes creation, installation, enabling/disabling, and disposing.
-- data retrieval is tool dependent, but each is encouraged to provide a default print() method for demo & debugging
- com.oracle.truffle.api.tools contains three instances, all language-agnostic:
-- LineToProbesMap: existing utility used by the debugger, adapted to the frameowrk
-- CoverageTracker: code coverage, tabulated by line
-- NodeExecCounter: raw execution counts, tabulated by node type, can be filtered by SyntaxTag
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Tue, 27 Jan 2015 20:26:41 -0800 |
parents | |
children | 3d2296dbace9 |
comparison
equal
deleted
inserted
replaced
18986:50b22daf6d53 | 18987:ac114ad31cdd |
---|---|
1 /* | |
2 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. | |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
4 * | |
5 * This code is free software; you can redistribute it and/or modify it | |
6 * under the terms of the GNU General Public License version 2 only, as | |
7 * published by the Free Software Foundation. Oracle designates this | |
8 * particular file as subject to the "Classpath" exception as provided | |
9 * by Oracle in the LICENSE file that accompanied this code. | |
10 * | |
11 * This code is distributed in the hope that it will be useful, but WITHOUT | |
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
14 * version 2 for more details (a copy is included in the LICENSE file that | |
15 * accompanied this code). | |
16 * | |
17 * You should have received a copy of the GNU General Public License version | |
18 * 2 along with this work; if not, write to the Free Software Foundation, | |
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
20 * | |
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
22 * or visit www.oracle.com if you need additional information or have any | |
23 * questions. | |
24 */ | |
25 package com.oracle.truffle.api.tools; | |
26 | |
27 import java.io.*; | |
28 import java.util.*; | |
29 import java.util.Map.Entry; | |
30 import java.util.concurrent.atomic.*; | |
31 | |
32 import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary; | |
33 import com.oracle.truffle.api.frame.*; | |
34 import com.oracle.truffle.api.instrument.*; | |
35 import com.oracle.truffle.api.instrument.impl.*; | |
36 import com.oracle.truffle.api.nodes.*; | |
37 import com.oracle.truffle.api.nodes.Node.Child; | |
38 import com.oracle.truffle.api.source.*; | |
39 | |
40 /** | |
41 * A {@link TruffleTool} that counts interpreter <em>execution calls</em> to AST nodes that hold a | |
42 * specified {@linkplain SyntaxTag tag}, tabulated by source and line number associated with each | |
43 * node. Tags are presumed to be applied external to the tool. If no tag is specified, | |
44 * {@linkplain StandardSyntaxTag#STATEMENT STATEMENT} is used, corresponding to conventional | |
45 * behavior for code coverage tools. | |
46 * <p> | |
47 * <b>Tool Life Cycle</b> | |
48 * <p> | |
49 * See {@link TruffleTool} for the life cycle common to all such tools. | |
50 * <p> | |
51 * <b>Execution Counts</b> | |
52 * <p> | |
53 * <ul> | |
54 * <li>"Execution call" on a node is is defined as invocation of a node method that is instrumented | |
55 * to produce the event {@link TruffleEventReceiver#enter(Node, VirtualFrame)};</li> | |
56 * <li>Execution calls are tabulated only at <em>instrumented</em> nodes, i.e. those for which | |
57 * {@linkplain Node#isInstrumentable() isInstrumentable() == true};</li> | |
58 * <li>Execution calls are tabulated only at nodes present in the AST when originally created; | |
59 * dynamically added nodes will not be instrumented.</li> | |
60 * </ul> | |
61 * </p> | |
62 * <b>Results</b> | |
63 * <p> | |
64 * A modification-safe copy of the {@linkplain #getCounts() counts} can be retrieved at any time, | |
65 * without effect on the state of the tool. | |
66 * </p> | |
67 * <p> | |
68 * A "default" {@linkplain #print(PrintStream) print()} method can summarizes the current counts at | |
69 * any time in a simple textual format, with no other effect on the state of the tool. | |
70 * </p> | |
71 * | |
72 * @see Instrument | |
73 * @see SyntaxTag | |
74 */ | |
75 public final class CoverageTracker extends TruffleTool { | |
76 | |
77 /** Counting data. */ | |
78 private final Map<LineLocation, CoverageCounter> counters = new HashMap<>(); | |
79 | |
80 /** For disposal. */ | |
81 private final List<Instrument> instruments = new ArrayList<>(); | |
82 | |
83 /** | |
84 * Counting is restricted to nodes holding this tag. | |
85 */ | |
86 private final SyntaxTag countingTag; | |
87 | |
88 private final ProbeListener probeListener; | |
89 | |
90 /** | |
91 * Create a per-line coverage tool for nodes tagged as {@linkplain StandardSyntaxTag#STATEMENT | |
92 * statements} in subsequently created ASTs. | |
93 */ | |
94 public CoverageTracker() { | |
95 this(StandardSyntaxTag.STATEMENT); | |
96 } | |
97 | |
98 /** | |
99 * Create a per-line coverage tool for nodes tagged as specified, presuming that tags applied | |
100 * outside this tool. | |
101 */ | |
102 public CoverageTracker(SyntaxTag tag) { | |
103 this.probeListener = new CoverageProbeListener(); | |
104 this.countingTag = tag; | |
105 } | |
106 | |
107 @Override | |
108 protected boolean internalInstall() { | |
109 Probe.addProbeListener(probeListener); | |
110 return true; | |
111 } | |
112 | |
113 @Override | |
114 protected void internalReset() { | |
115 counters.clear(); | |
116 } | |
117 | |
118 @Override | |
119 protected void internalDispose() { | |
120 Probe.removeProbeListener(probeListener); | |
121 for (Instrument instrument : instruments) { | |
122 instrument.dispose(); | |
123 } | |
124 } | |
125 | |
126 /** | |
127 * Gets a modification-safe summary of the current per-type node execution counts; does not | |
128 * affect the counts. | |
129 * <p> | |
130 * The map holds an array for each source, and elements of the a array corresponding to the | |
131 * textual lines of that source. An array entry contains null if the corresponding line of | |
132 * source is associated with no nodes of the relevant type, i.e. where no count was made. A | |
133 * numeric entry represents the execution count at the corresponding line of source. | |
134 * <p> | |
135 * <b>Note:</b> source line numbers are 1-based, so array index {@code i} corresponds to source | |
136 * line number {@code i + 1} | |
137 */ | |
138 public Map<Source, Long[]> getCounts() { | |
139 | |
140 /** | |
141 * Counters for every {Source, line number} for which a counter was installed, i.e. for | |
142 * every line associated with an appropriately tagged AST node; iterable in order of source | |
143 * name, then line number. | |
144 */ | |
145 final TreeSet<Entry<LineLocation, CoverageCounter>> entries = new TreeSet<>(new LineLocationEntryComparator()); | |
146 | |
147 final Map<Source, Long[]> results = new HashMap<>(); | |
148 | |
149 for (Entry<LineLocation, CoverageCounter> entry : counters.entrySet()) { | |
150 entries.add(entry); | |
151 } | |
152 Source curSource = null; | |
153 Long[] curLineTable = null; | |
154 for (Entry<LineLocation, CoverageCounter> entry : entries) { | |
155 final LineLocation key = entry.getKey(); | |
156 final Source source = key.getSource(); | |
157 final int lineNo = key.getLineNumber(); | |
158 if (source != curSource) { | |
159 if (curSource != null) { | |
160 results.put(curSource, curLineTable); | |
161 } | |
162 curSource = source; | |
163 curLineTable = new Long[source.getLineCount()]; | |
164 } | |
165 curLineTable[lineNo - 1] = entry.getValue().count.longValue(); | |
166 } | |
167 if (curSource != null) { | |
168 results.put(curSource, curLineTable); | |
169 } | |
170 return results; | |
171 } | |
172 | |
173 /** | |
174 * A default printer for the current line counts, producing lines of the form " (<count>) <line | |
175 * number> : <text of line>", grouped by source. | |
176 */ | |
177 public void print(PrintStream out) { | |
178 out.println(); | |
179 out.println(countingTag.name() + " coverage:"); | |
180 | |
181 /** | |
182 * Counters for every {Source, line number} for which a counter was installed, i.e. for | |
183 * every line associated with an appropriately tagged AST node; iterable in order of source | |
184 * name, then line number. | |
185 */ | |
186 final TreeSet<Entry<LineLocation, CoverageCounter>> entries = new TreeSet<>(new LineLocationEntryComparator()); | |
187 | |
188 for (Entry<LineLocation, CoverageCounter> entry : counters.entrySet()) { | |
189 entries.add(entry); | |
190 } | |
191 Source curSource = null; | |
192 int curLineNo = 1; | |
193 for (Entry<LineLocation, CoverageCounter> entry : entries) { | |
194 final LineLocation key = entry.getKey(); | |
195 final Source source = key.getSource(); | |
196 final int lineNo = key.getLineNumber(); | |
197 if (source != curSource) { | |
198 if (curSource != null) { | |
199 while (curLineNo <= curSource.getLineCount()) { | |
200 displayLine(out, null, curSource, curLineNo++); | |
201 } | |
202 } | |
203 curSource = source; | |
204 curLineNo = 1; | |
205 out.println(); | |
206 out.println(source.getPath()); | |
207 } | |
208 while (curLineNo < lineNo) { | |
209 displayLine(out, null, curSource, curLineNo++); | |
210 } | |
211 displayLine(out, entry.getValue().count, curSource, curLineNo++); | |
212 } | |
213 if (curSource != null) { | |
214 while (curLineNo <= curSource.getLineCount()) { | |
215 displayLine(out, null, curSource, curLineNo++); | |
216 } | |
217 } | |
218 } | |
219 | |
220 private static void displayLine(PrintStream out, AtomicLong value, Source source, int lineNo) { | |
221 if (value == null) { | |
222 out.format("%14s", " "); | |
223 } else { | |
224 out.format("(%12d)", value.longValue()); | |
225 } | |
226 out.format(" %3d: ", lineNo); | |
227 out.println(source.getCode(lineNo)); | |
228 } | |
229 | |
230 /** | |
231 * A receiver for events at each instrumented AST location. This receiver counts | |
232 * "execution calls" to the instrumented node and is <em>stateful</em>. State in receivers must | |
233 * be considered carefully since ASTs, along with all instrumentation (including event receivers | |
234 * such as this) are routinely cloned by the Truffle runtime. AST cloning is <em>shallow</em> | |
235 * (for non- {@link Child} nodes), so in this case the actual count <em>is shared</em> among all | |
236 * the clones; the count is also held in a table indexed by source line. | |
237 * <p> | |
238 * In contrast, a primitive field would <em>not</em> be shared among clones and resulting counts | |
239 * would not be accurate. | |
240 */ | |
241 private final class CoverageEventReceiver extends DefaultEventReceiver { | |
242 | |
243 /** | |
244 * Shared by all clones of the associated instrument and by the table of counters for the | |
245 * line. | |
246 */ | |
247 private final AtomicLong count; | |
248 | |
249 CoverageEventReceiver(AtomicLong count) { | |
250 this.count = count; | |
251 } | |
252 | |
253 @Override | |
254 @TruffleBoundary | |
255 public void enter(Node node, VirtualFrame frame) { | |
256 if (isEnabled()) { | |
257 count.getAndIncrement(); | |
258 } | |
259 } | |
260 } | |
261 | |
262 private static final class LineLocationEntryComparator implements Comparator<Entry<LineLocation, CoverageCounter>> { | |
263 | |
264 public int compare(Entry<LineLocation, CoverageCounter> e1, Entry<LineLocation, CoverageCounter> e2) { | |
265 return LineLocation.COMPARATOR.compare(e1.getKey(), e2.getKey()); | |
266 } | |
267 } | |
268 | |
269 /** | |
270 * Attach a counting instrument to each node that is assigned a specified tag. | |
271 */ | |
272 private class CoverageProbeListener extends DefaultProbeListener { | |
273 | |
274 @Override | |
275 public void probeTaggedAs(Probe probe, SyntaxTag tag, Object tagValue) { | |
276 if (countingTag == tag) { | |
277 | |
278 final SourceSection srcSection = probe.getProbedSourceSection(); | |
279 if (srcSection == null) { | |
280 // TODO (mlvdv) report this? | |
281 } else { | |
282 final LineLocation lineLocation = srcSection.getLineLocation(); | |
283 CoverageCounter counter = counters.get(lineLocation); | |
284 if (counter != null) { | |
285 // Another node starts on same line; count only the first (textually) | |
286 if (srcSection.getCharIndex() > counter.srcSection.getCharIndex()) { | |
287 // Counter already in place, corresponds to code earlier on line | |
288 return; | |
289 } else { | |
290 // Counter already in place, corresponds to later code; replace it | |
291 counter.instrument.dispose(); | |
292 } | |
293 } | |
294 final AtomicLong count = new AtomicLong(); | |
295 final CoverageEventReceiver eventReceiver = new CoverageEventReceiver(count); | |
296 final Instrument instrument = Instrument.create(eventReceiver, CoverageTracker.class.getSimpleName()); | |
297 instruments.add(instrument); | |
298 probe.attach(instrument); | |
299 counters.put(lineLocation, new CoverageCounter(srcSection, instrument, count)); | |
300 } | |
301 } | |
302 } | |
303 } | |
304 | |
305 private class CoverageCounter { | |
306 final SourceSection srcSection; | |
307 final Instrument instrument; | |
308 final AtomicLong count; | |
309 | |
310 CoverageCounter(SourceSection srcSection, Instrument instrument, AtomicLong count) { | |
311 this.srcSection = srcSection; | |
312 this.instrument = instrument; | |
313 this.count = count; | |
314 } | |
315 } | |
316 | |
317 } |