# HG changeset patch
# User Gilles Duboscq <duboscq@ssw.jku.at>
# Date 1377177746 -7200
# Node ID a268b0de65d6c91aa5d958d3f3b90d938232eeb4
# Parent  a8e618fd8868ca7a945422c8326b121b766c8125
Add some javadoc for GuardLoweringPhase, ConvertDeoptimizeToGuardPhase and DeoptimizeNode

diff -r a8e618fd8868 -r a268b0de65d6 graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizeNode.java
--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizeNode.java	Thu Aug 22 14:19:14 2013 +0200
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/DeoptimizeNode.java	Thu Aug 22 15:22:26 2013 +0200
@@ -28,6 +28,14 @@
 import com.oracle.graal.nodes.spi.*;
 import com.oracle.graal.nodes.type.*;
 
+/**
+ * This node represents an unconditional explicit request for immediate deoptimization.
+ * 
+ * After this node, execution will continue using a fallback execution engine (such as an
+ * interpreter) at the position described by the {@link #getDeoptimizationState() deoptimization
+ * state}.
+ * 
+ */
 @NodeInfo(shortName = "Deopt", nameTemplate = "Deopt {p#reason/s}")
 public class DeoptimizeNode extends ControlSinkNode implements Node.IterableNodeType, Lowerable, LIRLowerable, DeoptimizingNode {
 
diff -r a8e618fd8868 -r a268b0de65d6 graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/ConvertDeoptimizeToGuardPhase.java
--- a/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/ConvertDeoptimizeToGuardPhase.java	Thu Aug 22 14:19:14 2013 +0200
+++ b/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/ConvertDeoptimizeToGuardPhase.java	Thu Aug 22 15:22:26 2013 +0200
@@ -30,6 +30,15 @@
 import com.oracle.graal.nodes.util.*;
 import com.oracle.graal.phases.*;
 
+/**
+ * This phase will find branches which always end with a {@link DeoptimizeNode} and replace their
+ * {@link ControlSplitNode ControlSplitNodes} with {@link FixedGuardNode FixedGuardNodes}.
+ * 
+ * This is currently only done for branches that start from a {@link IfNode}. If it encounters a
+ * branch starting at an other kind of {@link ControlSplitNode}, it will only bring the
+ * {@link DeoptimizeNode} as close to the {@link ControlSplitNode} as possible.
+ * 
+ */
 public class ConvertDeoptimizeToGuardPhase extends Phase {
 
     private static AbstractBeginNode findBeginNode(Node startNode) {
diff -r a8e618fd8868 -r a268b0de65d6 graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/GuardLoweringPhase.java
--- a/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/GuardLoweringPhase.java	Thu Aug 22 14:19:14 2013 +0200
+++ b/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/GuardLoweringPhase.java	Thu Aug 22 15:22:26 2013 +0200
@@ -38,6 +38,18 @@
 import com.oracle.graal.phases.schedule.*;
 import com.oracle.graal.phases.tiers.*;
 
+/**
+ * This phase lowers {@link GuardNode GuardNodes} into corresponding control-flow structure and
+ * {@link DeoptimizeNode DeoptimizeNodes}.
+ * 
+ * This allow to enter a phase of the compiler where all node that may cause deoptimization are
+ * fixed.
+ * 
+ * It first makes a schedule in order to know where the control flow should be placed. Then, for
+ * each block, it applies two passes. The first one tries to replace null-check guards with implicit
+ * null checks performed by access to the objects that need to be null checked. The second phase
+ * does the actual control-flow expansion of the remaining {@link GuardNode GuardNodes}.
+ */
 public class GuardLoweringPhase extends BasePhase<MidTierContext> {
 
     private static class UseImplicitNullChecks extends ScheduledNodeIterator {