# HG changeset patch
# User Miguel Garcia <miguel.m.garcia@oracle.com>
# Date 1401290678 -7200
# Node ID aa28d876651a0c99f24b5f416aba1f194b26550a
# Parent  5eadeec4266857005deb5512162428e1086eab7e
[probability-cache] documentation, assertions added; unreachable code removed

diff -r 5eadeec42668 -r aa28d876651a graal/com.oracle.graal.phases/src/com/oracle/graal/phases/graph/FixedNodeProbabilityCache.java
--- a/graal/com.oracle.graal.phases/src/com/oracle/graal/phases/graph/FixedNodeProbabilityCache.java	Fri May 30 12:14:06 2014 +0200
+++ b/graal/com.oracle.graal.phases/src/com/oracle/graal/phases/graph/FixedNodeProbabilityCache.java	Wed May 28 17:24:38 2014 +0200
@@ -32,8 +32,7 @@
 import com.oracle.graal.nodes.*;
 
 /**
- * Compute probabilities for fixed nodes on the fly and cache at {@link BeginNode}s and
- * {@link ControlSplitNode}s.
+ * Compute probabilities for fixed nodes on the fly and cache them at {@link BeginNode}s.
  */
 public class FixedNodeProbabilityCache implements ToDoubleFunction<FixedNode> {
 
@@ -41,15 +40,44 @@
 
     private final Map<FixedNode, Double> cache = newIdentityMap();
 
+    /**
+     * <p>
+     * Given a {@link FixedNode} this method finds the most immediate {@link BeginNode} preceding it
+     * that either:
+     * <ul>
+     * <li>has no predecessor (ie, the begin-node is a merge, in particular a loop-begin, or the
+     * start-node)</li>
+     * <li>has a control-split predecessor</li>
+     * </ul>
+     * </p>
+     *
+     * <p>
+     * The thus found {@link BeginNode} is equi-probable with the {@link FixedNode} it was obtained
+     * from. When computed for the first time (afterwards a cache lookup returns it) that
+     * probability is computed as follows, again depending on the begin-node's predecessor:
+     * <ul>
+     * <li>No predecessor. In this case the begin-node is either:</li>
+     * <ul>
+     * <li>a merge-node, whose probability adds up those of its forward-ends</li>
+     * <li>a loop-begin, with probability as above multiplied by the loop-frequency</li>
+     * </ul>
+     * <li>Control-split predecessor: probability of the branch times that of the control-split</li>
+     * </ul>
+     * </p>
+     *
+     * <p>
+     * As an exception to all the above, a probability of 1 is assumed for a {@link FixedNode} that
+     * appears to be dead-code (ie, lacks a predecessor).
+     * </p>
+     *
+     */
     public double applyAsDouble(FixedNode node) {
         assert node != null;
         metricComputeNodeProbability.increment();
 
         FixedNode current = node;
         while (true) {
-            if (current == null) {
-                return 1D;
-            }
+            assert current != null;
             Node predecessor = current.predecessor();
             if (current instanceof BeginNode) {
                 if (predecessor == null) {
@@ -65,6 +93,7 @@
             current = (FixedNode) predecessor;
         }
 
+        assert current instanceof BeginNode;
         Double cachedValue = cache.get(current);
         if (cachedValue != null) {
             return cachedValue;