Track #66: document some considerations
diff --git a/org.jacoco.doc/diagrams/flow-3a.dot b/org.jacoco.doc/diagrams/flow-3a.dot
new file mode 100644
index 0000000..cac39e0
--- /dev/null
+++ b/org.jacoco.doc/diagrams/flow-3a.dot
@@ -0,0 +1,16 @@
+digraph G {
+ nodesep="0.2";
+ rankdir=LR;
+ node [shape="rect", penwidth="0.33", style="filled", fillcolor="#E0E0E0", margin="0,0.03", height="0.2", width="1.2", fontsize="10", fontname="Courier"];
+ edge [arrowsize="0.5"];
+ ordering="in";
+
+ i1 -> i2;
+
+ {
+ rank = same;
+ i1 [label="INSN 1"]
+ i2 [label="INSN 2"]
+ }
+
+}
diff --git a/org.jacoco.doc/diagrams/flow-3b.dot b/org.jacoco.doc/diagrams/flow-3b.dot
new file mode 100644
index 0000000..bb02688
--- /dev/null
+++ b/org.jacoco.doc/diagrams/flow-3b.dot
@@ -0,0 +1,17 @@
+digraph G {
+ nodesep="0.2";
+ rankdir=LR;
+ node [shape="rect", penwidth="0.33", style="filled", fillcolor="#E0E0E0", margin="0,0.03", height="0.2", width="1.2", fontsize="10", fontname="Courier"];
+ edge [arrowsize="0.5"];
+ ordering="in";
+
+ j1 -> p1 -> j2;
+
+ {
+ rank = same;
+ j1 [label="INSN 1"]
+ j2 [label="INSN 2"]
+ p1 [label="P", style="rounded,filled", fillcolor="#ffcc00", width="0.5"]
+
+ }
+}
diff --git a/org.jacoco.doc/diagrams/flow-4a.dot b/org.jacoco.doc/diagrams/flow-4a.dot
new file mode 100644
index 0000000..18256ea
--- /dev/null
+++ b/org.jacoco.doc/diagrams/flow-4a.dot
@@ -0,0 +1,16 @@
+digraph G {
+ nodesep="0.2";
+ rankdir=LR;
+ node [shape="rect", penwidth="0.33", style="filled", fillcolor="#E0E0E0", margin="0,0.03", height="0.2", width="1.2", fontsize="10", fontname="Courier"];
+ edge [arrowsize="0.5"];
+
+ {
+ ordering="in";
+ rank = same;
+ i1 -> i2 [headport="e", tailport="e"];
+
+ i1 [label="GOTO"]
+ i2 [label="TARGET INSN"]
+ }
+
+}
diff --git a/org.jacoco.doc/diagrams/flow-4b.dot b/org.jacoco.doc/diagrams/flow-4b.dot
new file mode 100644
index 0000000..7043463
--- /dev/null
+++ b/org.jacoco.doc/diagrams/flow-4b.dot
@@ -0,0 +1,18 @@
+digraph G {
+ nodesep="0.2";
+ rankdir=LR;
+ node [shape="rect", penwidth="0.33", style="filled", fillcolor="#E0E0E0", margin="0,0.03", height="0.2", width="1.2", fontsize="10", fontname="Courier"];
+ edge [arrowsize="0.5"];
+
+ {
+ ordering="in";
+ rank = same;
+ p1 -> i1;
+ i1 -> i2 [headport="e", tailport="e"];
+
+ i1 [label="GOTO"]
+ i2 [label="TARGET INSN"]
+ p1 [label="P", style="rounded,filled", fillcolor="#ffcc00", width="0.5"]
+ }
+
+}
diff --git a/org.jacoco.doc/diagrams/flow-5a.dot b/org.jacoco.doc/diagrams/flow-5a.dot
new file mode 100644
index 0000000..4e49691
--- /dev/null
+++ b/org.jacoco.doc/diagrams/flow-5a.dot
@@ -0,0 +1,18 @@
+digraph G {
+ nodesep="0.2";
+ rankdir=LR;
+ node [shape="rect", penwidth="0.33", style="filled", fillcolor="#E0E0E0", margin="0,0.03", height="0.2", width="1.2", fontsize="10", fontname="Courier"];
+ edge [arrowsize="0.5"];
+
+ {
+ ordering="in";
+ rank = same;
+ i1 -> i3 [headport="e", tailport="e"];
+ i1 -> i2;
+
+ i1 [label="IFxx", shape="diamond"]
+ i2 [label="NEXT INSN"]
+ i3 [label="TARGET INSN"]
+ }
+
+}
diff --git a/org.jacoco.doc/diagrams/flow-5b.dot b/org.jacoco.doc/diagrams/flow-5b.dot
new file mode 100644
index 0000000..b971853
--- /dev/null
+++ b/org.jacoco.doc/diagrams/flow-5b.dot
@@ -0,0 +1,22 @@
+digraph G {
+ nodesep="0.2";
+ rankdir=LR;
+ node [shape="rect", penwidth="0.33", style="filled", fillcolor="#E0E0E0", margin="0,0.03", height="0.2", width="1.2", fontsize="10", fontname="Courier"];
+ edge [arrowsize="0.5"];
+
+ {
+ ordering="in";
+ rank = same;
+ i1 -> i2 [headport="e", tailport="e"];
+ i1 -> p1;
+ p1 -> i4;
+ i4 -> i3 [headport="e", tailport="e"];
+
+ i1 [label="NOT IFxx", shape="diamond"]
+ i2 [label="NEXT INSN"]
+ i3 [label="TARGET INSN"]
+ i4 [label="GOTO"]
+ p1 [label="P", style="rounded,filled", fillcolor="#ffcc00", width="0.5"]
+ }
+
+}
diff --git a/org.jacoco.doc/diagrams/render.sh b/org.jacoco.doc/diagrams/render.sh
index 49d03e8..6805cd1 100644
--- a/org.jacoco.doc/diagrams/render.sh
+++ b/org.jacoco.doc/diagrams/render.sh
@@ -2,5 +2,11 @@
OUTPUT=../docroot/doc/.resources
-dot -Tpng -o$OUTPUT/flow-1.png flow-1.dot
-dot -Tpng -o$OUTPUT/flow-2.png flow-2.dot
\ No newline at end of file
+dot -Tpng -o$OUTPUT/flow-1.png flow-1.dot
+dot -Tpng -o$OUTPUT/flow-2.png flow-2.dot
+dot -Tpng -o$OUTPUT/flow-3a.png flow-3a.dot
+dot -Tpng -o$OUTPUT/flow-3b.png flow-3b.dot
+dot -Tpng -o$OUTPUT/flow-4a.png flow-4a.dot
+dot -Tpng -o$OUTPUT/flow-4b.png flow-4b.dot
+dot -Tpng -o$OUTPUT/flow-5a.png flow-5a.dot
+dot -Tpng -o$OUTPUT/flow-5b.png flow-5b.dot
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-1.png b/org.jacoco.doc/docroot/doc/.resources/flow-1.png
index 6938e36..a6ce7cd 100644
--- a/org.jacoco.doc/docroot/doc/.resources/flow-1.png
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-1.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-2.png b/org.jacoco.doc/docroot/doc/.resources/flow-2.png
index f118938..5cc767f 100644
--- a/org.jacoco.doc/docroot/doc/.resources/flow-2.png
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-2.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-3.png b/org.jacoco.doc/docroot/doc/.resources/flow-3.png
new file mode 100644
index 0000000..7320e93
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-3.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-3a.png b/org.jacoco.doc/docroot/doc/.resources/flow-3a.png
new file mode 100644
index 0000000..71c4c34
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-3a.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-3b.png b/org.jacoco.doc/docroot/doc/.resources/flow-3b.png
new file mode 100644
index 0000000..5a7fd3e
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-3b.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-4a.png b/org.jacoco.doc/docroot/doc/.resources/flow-4a.png
new file mode 100644
index 0000000..5b11b52
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-4a.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-4b.png b/org.jacoco.doc/docroot/doc/.resources/flow-4b.png
new file mode 100644
index 0000000..ec0ad57
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-4b.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-5a.png b/org.jacoco.doc/docroot/doc/.resources/flow-5a.png
new file mode 100644
index 0000000..aa64579
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-5a.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/.resources/flow-5b.png b/org.jacoco.doc/docroot/doc/.resources/flow-5b.png
new file mode 100644
index 0000000..73cd195
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/.resources/flow-5b.png
Binary files differ
diff --git a/org.jacoco.doc/docroot/doc/flow.html b/org.jacoco.doc/docroot/doc/flow.html
index 53b0def..07e90ef 100644
--- a/org.jacoco.doc/docroot/doc/flow.html
+++ b/org.jacoco.doc/docroot/doc/flow.html
@@ -144,14 +144,22 @@
</tbody>
</table>
+<p>
+ For the first implementation approach we ignore edges caused by exceptions
+ and the the method entry. This means we consider SEQUENCE, JUMP and EXIT.
+</p>
+
<h2>Probe Insertion Strategy</h2>
+<p>
+ Probes are additional instructions that can be inserted between existing
+ instructions. Probes record the fact that they have been executed. One can
+ think probes are placed on edges of the control flow graph. Therefore if a
+ probe has been executed we know that the corresponding edge has been visited.
+ From this edge we can conclude to other preceding nodes and edges:
+</p>
+
<ul>
- <li>Probes are additional instructions that can be inserted between existing
- instructions. Probes record the fact that they have been executed. One can
- think probes are placed on edges of the control flow graph. Therefore if
- a probe has been executed we know that the corresponding edge has been
- visited.</li>
<li>If a edge has been visited, we know that the source node of the this edge
has been executed.</li>
<li>If a node has been executed and the node is the target of only one edge
@@ -169,15 +177,52 @@
</ul>
<p>
- The execution status of all other edges and instructions can be derived from
- the status of this probes by recursively applying the rules above.
+ Given the example method above we see that <code>INVOKE d()</code> is the only
+ node with more than one incoming edge. So we need to place probes on those
+ edges and another probe on the only exit node:
</p>
<img src=".resources/flow-2.png" alt="Probe positions"/>
+<p>
+ <i>TODO: Insertion strategies for SEQUENCE</i>
+</p>
+
+<img src=".resources/flow-3.png" alt="SEQUENCE Probe"/>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Type</td>
+ <td>Before</td>
+ <td>After</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>SEQUENCE</td>
+ <td><img src=".resources/flow-3a.png" alt="SEQUENCE"/></td>
+ <td><img src=".resources/flow-3b.png" alt="SEQUENCE with Probe"/></td>
+ </tr>
+ <tr>
+ <td>JUMP (unconditional)</td>
+ <td><img src=".resources/flow-4a.png" alt="JUMP"/></td>
+ <td><img src=".resources/flow-4b.png" alt="JUMP with Probe"/></td>
+ </tr>
+ <tr>
+ <td>JUMP (conditional)</td>
+ <td><img src=".resources/flow-5a.png" alt="JUMP"/></td>
+ <td><img src=".resources/flow-5b.png" alt="JUMP with Probe"/></td>
+ </tr>
+ </tbody>
+</table>
<h2>Coverage Analysis</h2>
+<p>
+ The execution status of all other edges and instructions can be derived from
+ the status of this probes by recursively applying the rules above.
+</p>
<h2>Probe Implementation</h2>
