Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 096bd1dd31408d3599d0e8bbedf9699a667db999 / . / org.jacoco.doc / docroot / doc / flow.html
blob: 3b57997fbc8ea4dc8c84d105247e9b69fbdaa5ad [file] [log] [blame]
Marc R. Hoffmann096bd1d2010-04-27 04:21:39 +0000[diff] [blame^]1<?xml version="1.0" encoding="ISO-8859-1" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
4<head>
5 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
6 <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
7 <title>JaCoCo - Control Flow Analysis</title>
8</head>
9<body>
10
11<div class="breadcrumb">
12 <a href="../index.html" class="el_session">JaCoCo</a> &gt;
13 <a href="index.html" class="el_group">Documentation</a> &gt;
14 <span class="el_source">Control Flow Analysis</span>
15</div>
16<div id="content">
17
18<h1>Control Flow Analysis for Java Methods</h1>
19
20<p style="font-weight:bold;">
21 DRAFT - This document does not reflect the current JaCoCo implementation.
22</p>
23
24<p class="hint">
25 Implementing a coverage tool for branch coverage requires detailed analysis
26 of the internal control flow of Java methods. Due to the architecture of
27 JaCoCo this analysis needs to happen on compiled class files (byte code).
28 This document defines graph structures for control flow analysis of Java byte
29 code and discusses strategies for probe insertion. Marc R. Hoffmann, April 2010
30</p>
31
32<h2>Motivation and Requirements</h2>
33
34<ul>
35 <li>Path Coverage</li>
36 <li>Exception Detection</li>
37</ul>
38
39<h2>The Control Flow Graph</h2>
40
41<ul>
42 <li>Virtual Entry and Exit Nodes</li>
43 <li>Subsequent Instructions</li>
44 <li>(Conditional) Jump</li>
45 <li>Table/Lookup Switch</li>
46 <li>Exception Handlers</li>
47 <li>Unhandled Exceptions</li>
48</ul>
49
50<h2>Probe Insertion</h2>
51
52<p>
53 Code coverage analysis is a runtime metric that provides execution details
54 of the software under test. This requires detailed recording about the
55 instructions (instruction coverage) that have been executed. For path coverage
56 also the outcome of decisions has to be recorded. In any case execution data
57 is collected by so called probes:
58</p>
59
60<p class="hint">
61 A <b>probe</b> is a sequence of byte code instructions that can be inserted
62 into a Java method. When the probe is executed, this fact is recorded and can
63 be reported by the coverage runtime.
64</p>
65
66<p>
67 The only purpose of the probe is to record that it has been executed at least
68 once. The probe does not record the number of times it has been called or
69 collect any timing information. The latter is out of scope for code coverage
70 analysis and more in the objective of a performance analysis tool. Typically
71 multiple probes needs to be inserted into each method, therefore probes needs
72 to be identified. Also the probe implementation and the storage mechanism it
73 depends on needs to be thread safe as multi-threaded execution is a common
74 scenario for java applications (albeit not for plain unit tests). Probes must
75 not have any side effects on the original code of the method. Also they should
76 add minimal overhead.
77</p>
78
79<p>
80 So to summarize the requirements for execution probes:
81</p>
82
83<ul>
84 <li>Record execution</li>
85 <li>Identification for different probes</li>
86 <li>Thread safe</li>
87 <li>No side effects on application code</li>
88 <li>Minimal runtime overhead</li>
89</ul>
90
91<p>
92 JaCoCo implements probes with a <code>boolean[]</code> array instance per
93 class. Each probe corresponds to a entry in this array. Whenever the probe is
94 executed the entry is set to <code>true</code> with the following four byte
95 code instructions:
96</p>
97
98<pre class="source">
99ALOAD probearray
100xPUSH probeid
101ICONST_1
102BASTORE
103</pre>
104
105<p>
106 Note that this probe code is thread safe, does not modify the operand stack
107 or modify local variables and is also thread safe. It does also not leave the
108 method though an external call. The only prerequisite is that the probe array
109 is available as a local variable. For this at the beginning of each method
110 additional instrumentation code needs to be added to obtain the array instance
111 associated with the belonging class (to avoid code duplication the
112 initialization is delegated to a method <code>$jacocoinit()</code> which is
113 added to every non-interface class).
114</p>
115
116<ul>
117 <li>Byte code size per Probe</li>
118 <li>Limitation: Only proves that the probe itself has been executed,
119 assumptions about the surrounding application code is interpolation</li>
120 <li>Probe in every edge of the control flow graph</li>
121 <li>Every exit path known (branch coverage)</li>
122 <li>Block entry known (exceptions within blocks)</li>
123</ul>
124
125<h2>Different Types of Edges</h2>
126
127<ul>
128 <li>Probe insertion strategies</li>
129</ul>
130
131<h2>Runtime Overhead</h2>
132
133<ul>
134 <li>Comparison to current basic block probes</li>
135</ul>
136
137</div>
138<div class="footer">
139 <div class="versioninfo"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</div>
140 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
141</div>
142
143</body>
144</html>