Mercurial > hg > graal-jvmci-8

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/tools/CoverageTracker.java @ 18987:ac114ad31cdd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 }