# HG changeset patch
# User Doug Simon <doug.simon@oracle.com>
# Date 1371038281 -7200
# Node ID 0478f70900de270cdba3d1d74c14275344cf6b60
# Parent  8cffc5183a277e9492e3bc01f3262a9e6bb18386
extra javadoc for intricacies involved in lowering ExceptionObjectNode

diff -r 8cffc5183a27 -r 0478f70900de graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/java/ExceptionObjectNode.java
--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/java/ExceptionObjectNode.java	Wed Jun 12 13:55:40 2013 +0200
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/java/ExceptionObjectNode.java	Wed Jun 12 13:58:01 2013 +0200
@@ -24,6 +24,7 @@
 
 import static com.oracle.graal.api.meta.LocationIdentity.*;
 
+import com.oracle.graal.api.code.*;
 import com.oracle.graal.api.meta.*;
 import com.oracle.graal.nodes.*;
 import com.oracle.graal.nodes.extended.*;
@@ -54,6 +55,13 @@
         return (stamp() == StampFactory.forVoid());
     }
 
+    /**
+     * The frame state upon entry to an exception handler is such that it is a
+     * {@link BytecodeFrame#rethrowException rethrow exception} state and the stack contains exactly
+     * the exception object (per the JVM spec) to rethrow. This means that the code creating this
+     * state (i.e. the {@link LoadExceptionObjectNode}) cannot cause a deoptimization as the
+     * runtime/interpreter would not have a valid location for the exception object to be rethrown.
+     */
     @Override
     public void lower(LoweringTool tool, LoweringType loweringType) {
         if (isLowered()) {
diff -r 8cffc5183a27 -r 0478f70900de graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/java/LoadExceptionObjectNode.java
--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/java/LoadExceptionObjectNode.java	Wed Jun 12 13:55:40 2013 +0200
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/java/LoadExceptionObjectNode.java	Wed Jun 12 13:58:01 2013 +0200
@@ -22,6 +22,7 @@
  */
 package com.oracle.graal.nodes.java;
 
+import com.oracle.graal.api.code.*;
 import com.oracle.graal.nodes.*;
 import com.oracle.graal.nodes.spi.*;
 import com.oracle.graal.nodes.type.*;
@@ -29,6 +30,12 @@
 /**
  * Loads an exception object passed by the runtime from a callee to an exception handler in a
  * caller. The node is only produced when lowering an {@link ExceptionObjectNode}.
+ * <p>
+ * The frame state upon entry to an exception handler is such that it is a
+ * {@link BytecodeFrame#rethrowException rethrow exception} state and the stack contains exactly the
+ * exception object (per the JVM spec) to rethrow. This means that the code generated for this node
+ * must not cause a deoptimization as the runtime/interpreter would not have a valid location to
+ * find the exception object to be rethrown.
  */
 public class LoadExceptionObjectNode extends AbstractStateSplit implements Lowerable {