Add hint to methods used when handling StackOverflowError

Author: fangerer

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonContext.java

@@ -2151,6 +2151,12 @@ public PythonNativeWrapper getSingletonNativeWrapper(PythonAbstractObject obj) {
         return null;
     }
 
+    /**
+     * This method is intended to be called to re-acquire the GIL after a {@link StackOverflowError}
+     * was catched. To reduce the probability that re-acquiring the GIL causes again a
+     * {@link StackOverflowError}, it is important to keep this method as simple as possible. In
+     * particular, do not add calls if there is a way to avoid it.
+     */
     public void reacquireGilAfterStackOverflow() {
         while (!ownsGil()) {
             try {

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/exception/PException.java

@@ -122,6 +122,12 @@ private static RuntimeException createStacktraceCarrier() {
         return new RuntimeException();
     }
 
+    /*
+     * Note: we use this method to convert a Java StackOverflowError into a Python RecursionError.
+     * At the time when this is done, some Java stack frames were already unwinded but there is no
+     * guarantee on how many. Therefore, it is important that this method is simple. In particular,
+     * do not add calls if that can be avoided.
+     */
     public static PException fromObject(PBaseException actual, Node node, Throwable wrapped) {
         PException pException = new PException(actual, node, wrapped);
         actual.setException(pException);

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/object/PythonObjectFactory.java

@@ -933,6 +933,12 @@ public final PBaseException createBaseException(Object cls, Object[] data, PTupl
         return trace(new PBaseException(cls, getShape(cls), data, args));
     }
 
+    /*
+     * Note: we use this method to convert a Java StackOverflowError into a Python RecursionError.
+     * At the time when this is done, some Java stack frames were already unwinded but there is no
+     * guarantee on how many. Therefore, it is important that this method is simple. In particular,
+     * do not add calls if that can be avoided.
+     */
     public final PBaseException createBaseException(Object cls, TruffleString format, Object[] args) {
         return createBaseException(cls, null, format, args);
     }