# HG changeset patch
# User Gilles Duboscq <duboscq@ssw.jku.at>
# Date 1386771335 -3600
# Node ID 5215f94f94ec4810c09f770dd510a3764c8c979e
# Parent  a8964e9bb9483cea1d2051b3c0c20dba191fea0f
GRAAL-632: Clarify difference between states managed by StateSplit and DeoptimizingNode

diff -r a8964e9bb948 -r 5215f94f94ec graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizingFixedWithNextNode.java
--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizingFixedWithNextNode.java	Wed Dec 11 16:28:15 2013 +0100
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizingFixedWithNextNode.java	Wed Dec 11 15:15:35 2013 +0100
@@ -26,7 +26,7 @@
 
 public abstract class DeoptimizingFixedWithNextNode extends FixedWithNextNode implements DeoptimizingNode {
 
-    @Input private FrameState deoptState;
+    @Input(notDataflow = true) private FrameState deoptState;
 
     public DeoptimizingFixedWithNextNode(Stamp stamp) {
         super(stamp);
diff -r a8964e9bb948 -r 5215f94f94ec graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizingNode.java
--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizingNode.java	Wed Dec 11 16:28:15 2013 +0100
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizingNode.java	Wed Dec 11 15:15:35 2013 +0100
@@ -25,7 +25,7 @@
 import com.oracle.graal.nodes.spi.*;
 
 /**
- * Interface implemented by nodes which need deoptimization information.
+ * Interface implemented by nodes which may need {@linkplain FrameState deoptimization information}.
  */
 public interface DeoptimizingNode extends NodeWithState {
 
@@ -42,7 +42,7 @@
     /**
      * Sets the deoptimization information associated with this node.
      * 
-     * @param state the FrameState which represents the deoptimization information
+     * @param state the {@link FrameState} which represents the deoptimization information
      */
     void setDeoptimizationState(FrameState state);
 }
diff -r a8964e9bb948 -r 5215f94f94ec graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/FrameState.java
--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/FrameState.java	Wed Dec 11 16:28:15 2013 +0100
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/FrameState.java	Wed Dec 11 15:15:35 2013 +0100
@@ -33,6 +33,8 @@
 /**
  * The {@code FrameState} class encapsulates the frame state (i.e. local variables and operand
  * stack) at a particular point in the abstract interpretation.
+ * 
+ * This can be used as debug or deoptimization information.
  */
 @NodeInfo(nameTemplate = "FrameState@{p#method/s}:{p#bci}")
 public final class FrameState extends VirtualState implements IterableNodeType {
diff -r a8964e9bb948 -r 5215f94f94ec graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/StateSplit.java
--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/StateSplit.java	Wed Dec 11 16:28:15 2013 +0100
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/StateSplit.java	Wed Dec 11 15:15:35 2013 +0100
@@ -30,19 +30,21 @@
 public interface StateSplit extends NodeWithState {
 
     /**
-     * Gets the state of the JVM frame after execution of this node.
+     * Gets the {@link FrameState} corresponding to the state of the JVM after execution of this
+     * node.
      */
     FrameState stateAfter();
 
     /**
-     * Sets the state of the JVM frame after execution of this node.
+     * Sets the {@link FrameState} corresponding to the state of the JVM after execution of this
+     * node.
      */
     void setStateAfter(FrameState x);
 
     /**
-     * Determines if this node has a side-effect. Execution of such a node changes state visible to
-     * other threads. These nodes denote boundaries across which deoptimization points cannot be
-     * moved.
+     * Determines if this node has a side-effect. Such nodes can not be safely re-executed because
+     * they modified state which is visible to other thread or modified state beyond what is
+     * captured in {@link FrameState} nodes.
      */
     boolean hasSideEffect();
 }
diff -r a8964e9bb948 -r 5215f94f94ec graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/spi/NodeWithState.java
--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/spi/NodeWithState.java	Wed Dec 11 16:28:15 2013 +0100
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/spi/NodeWithState.java	Wed Dec 11 15:15:35 2013 +0100
@@ -22,9 +22,28 @@
  */
 package com.oracle.graal.nodes.spi;
 
+import com.oracle.graal.graph.*;
 import com.oracle.graal.nodes.*;
+import static com.oracle.graal.nodes.StructuredGraph.GuardsStage.*;
 
+/**
+ * Interface for nodes which have {@link FrameState} nodes as input.
+ * <p>
+ * Some node can declare more than one interface which requires a {@link FrameState} input (e.g.
+ * {@link DeoptimizingNode} and {@link StateSplit}). Since this interface can only report one
+ * {@link FrameState}, such nodes must ensure they only maintain a link to at most one
+ * {@link FrameState} at all times. Usually this is not a problem because {@link FrameState} are
+ * associated only with {@link StateSplit} nodes before the {@link #AFTER_FSA} stage and only with
+ * {@link DeoptimizingNode} after.
+ * 
+ * 
+ */
 public interface NodeWithState {
+    /**
+     * Gets the {@link FrameState} associated with this node.
+     * 
+     * @return the {@link FrameState} associated with this node
+     */
     FrameState getState();
 
     Node asNode();
diff -r a8964e9bb948 -r 5215f94f94ec graal/com.oracle.graal.phases/src/com/oracle/graal/phases/schedule/SchedulePhase.java
--- a/graal/com.oracle.graal.phases/src/com/oracle/graal/phases/schedule/SchedulePhase.java	Wed Dec 11 16:28:15 2013 +0100
+++ b/graal/com.oracle.graal.phases/src/com/oracle/graal/phases/schedule/SchedulePhase.java	Wed Dec 11 15:15:35 2013 +0100
@@ -887,7 +887,7 @@
                         closure.apply(cfg.getNodeToBlock().get(pred));
                     }
                 } else {
-                    // For the time being, only FrameStates can be connected to StateSplits.
+                    // For the time being, FrameStates can only be connected to NodeWithState.
                     if (!(usage instanceof FrameState)) {
                         throw new SchedulingError(usage.toString());
                     }