[GR-54518] Polish Continuations API

PullRequest: graal/18046

Author: rakachan

espresso/docs/continuations.md

@@ -10,7 +10,8 @@ can be serialized to resume execution in a different JVM running the same code (
 See the JavaDoc of the `org.graalvm.continuations` package, and make sure to add the `continuations.jar` in the Espresso
 distribution to your classpath when compiling (but not at runtime).
 
-Currently, only the Espresso VM supports the continuations feature.
+Currently, only the Espresso VM supports the continuations feature. Since it is still experimental, the option needs to
+be enabled by using the flags `--experimental-options --java.Continuum=true`.
 
 ### High level
 
@@ -21,36 +22,36 @@ implement `generate` and call `emit` from inside it.
 ### Low level
 
 You create a new `Continuation` by passing the constructor an object that implements the functional
-interface `Continuation.EntryPoint` (which can be a lambda). That object's `start` method receives
-a `Continuation.SuspendCapability` that lets you trigger a suspend. You can do that from _any_ depth in the stack as
-long as the code was invoked via the entry point, and all the frames between the call to `suspend` and `start` will be
+interface `ContinuationEntryPoint` (which can be a lambda). That object's `start` method receives
+a `SuspendCapability` that lets you trigger suspension. You can do that from _any_ depth in the stack as
+long as the code was invoked via the entry point, and all the frames between the call to `suspend` and `resume` will be
 unwound and stored inside the `Continuation` object. You can then call `resume()` on it to kick it off for the first
 time or to restart from the last suspend point.
 
 Continuations are single-threaded constructs. There are no second threads involved, and the `resume()` method blocks
-until the continuation either finishes successfully, throws an exception or calls suspend. The difference can be seen in
-the result of the `getState()` method.
+until the continuation either finishes successfully, throws an exception or calls suspend. `isResumable()` can be called
+to determine if the continuation can be resumed (if the continuation has been freshly created or it has been previously
+suspended), and `isCompleted()` can be called to determine if the continuation has completed (either by returning
+normally, or if an exception escaped).
 
-`Continuation` implements `Externalizable` and can serialize to a backwards compatible format (not guaranteed until
-final release). Because frames can point to anything in their parameters and local variables, it must be persisted by a
-serialization engine that can handle arbitrary objects like [Kryo](https://github.com/EsotericSoftware/kryo/)
-or `ObjectOutputStream`.
+`Continuation` implements `Serializable` and can serialize to a backwards compatible format. Because frames can point to
+anything in their parameters and local variables, the class `ContinuationSerializable` provides static
+methods `readObjectExternal` and `writeObjectExternal` which may be used to coordinate serialization of
+continuation-related objects with a non-jdk serialization engine.
 
 ## Security
 
 Continuations that have **not** been _materialized_ are safe, as the frame record is kept internal to the VM.
 
 Materializing a continuation refers to making the record visible to Java code, through the
-private `Continuation.stackFrameHead` field.
-
-Currently, the only path for materialization is through serialization.
+private `ContinuationImpl.stackFrameHead` field. Currently, the only path for materialization is through serialization.
 
 When restoring from a materialized frame (_dematerialization_), only minimal checks are performed by the VM, and only to
 prevent a VM crash. Examples of these checks are:
 
 - Ensures that resume only happens on `invoke` bytecodes.
 - Ensures that the recorded frame data is consistent with what was computed by the bytecode verifier.
-- Ensures that the last frame in the record is `Continuation.suspend`.
+- Ensures that the last frame in the record is `ContinuationImpl.suspend`.
 
 Deserializing a continuation supplied by an attacker will allow complete takeover of the JVM. Only resume continuations
 you persisted yourself!
@@ -129,15 +130,15 @@ Furthermore, there is currently no support for continuation-in-continuation.
 
 *This section is only relevant for people working on Espresso itself.*
 
-Continuations interact with the VM via private intrinsics registered on the `Continuation` class.
+Continuations interact with the VM via private intrinsics registered on the `Continuation` and `ContinuationImpl` class.
 
 A continuation starts by calling into the VM. Execution resurfaces in the guest world at the private `run` method of
-`Continuation`, which then invokes the user's given entry point.
+`ContinuationImpl`, which then invokes the user's given entry point.
 
 Suspending throws a host-side exception that is caught by the `BytecodeNode` interpreter loop. The stack frame is copied
 into a new host-side object called a `HostFrameRecord` (HFR). The exception is then rethrown. The HFRs are chained
-together in a linked list. Once execution reaches the private `run` method of `Continuation` the HFR list is attached
-into a hidden field of `Continuation`. Control is then returned to the guest.
+together in a linked list. Once execution reaches the private `run` method of `ContinuationImpl` the HFR list is
+attached into a hidden field of `ContinuationImpl`. Control is then returned to the guest.
 
 On resuming a `Continuation`, the entire call stack needs to be re-winded. This happens through a different `CallTarget`
 than for regular calls, and there is one such call target per encountered resume `bci`.
@@ -149,7 +150,7 @@ we pass the rest of the records to the next method. This is all done in a specia
 The separation of the call targets has two advantages:
 
 - It does not interfere with regular calls.
-- Resuming and suspending can be PE'd, leading to fast suspend/resume cycles.
+- Resuming and suspending can be partial-evaluated, leading to fast suspend/resume cycles.
 
-Serialization is done entirely in guest-side code, by having the `Continuation` class implement `Externalizable`. The
+Serialization is done entirely in guest-side code, by having the `Continuation` class implement `Serializable`. The
 format is designed to enable backwards-compatible evolution of the format.

espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/descriptors/Symbol.java

@@ -1018,10 +1018,10 @@ public static void ensureInitialized() {
                         "Lcom/oracle/truffle/espresso/polyglot/impl/EspressoForeignNumber;");
 
         // Continuations
-        public static final Symbol<Type> org_graalvm_continuations_Continuation = StaticSymbols.putType(
-                        "Lorg/graalvm/continuations/Continuation;");
-        public static final Symbol<Type> org_graalvm_continuations_Continuation_FrameRecord = StaticSymbols.putType(
-                        "Lorg/graalvm/continuations/Continuation$FrameRecord;");
+        public static final Symbol<Type> org_graalvm_continuations_ContinuationImpl = StaticSymbols.putType(
+                        "Lorg/graalvm/continuations/ContinuationImpl;");
+        public static final Symbol<Type> org_graalvm_continuations_ContinuationImpl_FrameRecord = StaticSymbols.putType(
+                        "Lorg/graalvm/continuations/ContinuationImpl$FrameRecord;");
         public static final Symbol<Type> org_graalvm_continuations_IllegalMaterializedRecordException = StaticSymbols.putType(
                         "Lorg/graalvm/continuations/IllegalMaterializedRecordException;");
         public static final Symbol<Type> org_graalvm_continuations_IllegalContinuationStateException = StaticSymbols.putType(

espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/impl/LinkedKlassFieldLayout.java

@@ -240,7 +240,7 @@ private static class HiddenField {
                                         new HiddenField(Name.HIDDEN_TREGEX_SEARCH_FROM_BACKUP),
                                         new HiddenField(Name.HIDDEN_TREGEX_MATCHING_MODE_BACKUP)
                         }),
-                        entry(Type.org_graalvm_continuations_Continuation, new HiddenField[]{
+                        entry(Type.org_graalvm_continuations_ContinuationImpl, new HiddenField[]{
                                         new HiddenField(Name.HIDDEN_CONTINUATION_FRAME_RECORD)
                         }));
 

espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/meta/Meta.java

@@ -1928,36 +1928,36 @@ private DiffVersionLoadHelper diff() {
     @CompilationFinal public Method java_beans_Introspector_flushFromCaches;
 
     public final class ContinuumSupport {
-        public final Method org_graalvm_continuations_Continuation_run;
-        public final Method org_graalvm_continuations_Continuation_suspend;
-        public final Field org_graalvm_continuations_Continuation_stackFrameHead;
+        public final Method org_graalvm_continuations_ContinuationImpl_run;
+        public final Method org_graalvm_continuations_ContinuationImpl_suspend;
+        public final Field org_graalvm_continuations_ContinuationImpl_stackFrameHead;
         public final Field HIDDEN_CONTINUATION_FRAME_RECORD;
-        public final ObjectKlass org_graalvm_continuations_Continuation_FrameRecord;
-        public final Field org_graalvm_continuations_Continuation_FrameRecord_pointers;
-        public final Field org_graalvm_continuations_Continuation_FrameRecord_primitives;
-        public final Field org_graalvm_continuations_Continuation_FrameRecord_method;
-        public final Field org_graalvm_continuations_Continuation_FrameRecord_next;
-        public final Field org_graalvm_continuations_Continuation_FrameRecord_bci;
+        public final ObjectKlass org_graalvm_continuations_ContinuationImpl_FrameRecord;
+        public final Field org_graalvm_continuations_ContinuationImpl_FrameRecord_pointers;
+        public final Field org_graalvm_continuations_ContinuationImpl_FrameRecord_primitives;
+        public final Field org_graalvm_continuations_ContinuationImpl_FrameRecord_method;
+        public final Field org_graalvm_continuations_ContinuationImpl_FrameRecord_next;
+        public final Field org_graalvm_continuations_ContinuationImpl_FrameRecord_bci;
         public final ObjectKlass org_graalvm_continuations_IllegalMaterializedRecordException;
         public final ObjectKlass org_graalvm_continuations_IllegalContinuationStateException;
 
         private ContinuumSupport() {
-            ObjectKlass org_graalvm_continuations_Continuation = knownKlass(Type.org_graalvm_continuations_Continuation);
-            org_graalvm_continuations_Continuation_run = org_graalvm_continuations_Continuation.requireDeclaredMethod(Name.run, Signature._void);
-            org_graalvm_continuations_Continuation_suspend = org_graalvm_continuations_Continuation.requireDeclaredMethod(Name.suspend, Signature._void);
-            org_graalvm_continuations_Continuation_stackFrameHead = org_graalvm_continuations_Continuation.requireDeclaredField(Name.stackFrameHead,
-                            Type.org_graalvm_continuations_Continuation_FrameRecord);
-            HIDDEN_CONTINUATION_FRAME_RECORD = org_graalvm_continuations_Continuation.requireHiddenField(Name.HIDDEN_CONTINUATION_FRAME_RECORD);
-            org_graalvm_continuations_Continuation_FrameRecord = knownKlass(Type.org_graalvm_continuations_Continuation_FrameRecord);
-            org_graalvm_continuations_Continuation_FrameRecord_pointers = org_graalvm_continuations_Continuation_FrameRecord.requireDeclaredField(
+            ObjectKlass org_graalvm_continuations_ContinuationImpl = knownKlass(Type.org_graalvm_continuations_ContinuationImpl);
+            org_graalvm_continuations_ContinuationImpl_run = org_graalvm_continuations_ContinuationImpl.requireDeclaredMethod(Name.run, Signature._void);
+            org_graalvm_continuations_ContinuationImpl_suspend = org_graalvm_continuations_ContinuationImpl.requireDeclaredMethod(Name.suspend, Signature._void);
+            org_graalvm_continuations_ContinuationImpl_stackFrameHead = org_graalvm_continuations_ContinuationImpl.requireDeclaredField(Name.stackFrameHead,
+                            Type.org_graalvm_continuations_ContinuationImpl_FrameRecord);
+            HIDDEN_CONTINUATION_FRAME_RECORD = org_graalvm_continuations_ContinuationImpl.requireHiddenField(Name.HIDDEN_CONTINUATION_FRAME_RECORD);
+            org_graalvm_continuations_ContinuationImpl_FrameRecord = knownKlass(Type.org_graalvm_continuations_ContinuationImpl_FrameRecord);
+            org_graalvm_continuations_ContinuationImpl_FrameRecord_pointers = org_graalvm_continuations_ContinuationImpl_FrameRecord.requireDeclaredField(
                             Name.pointers, Type.java_lang_Object_array);
-            org_graalvm_continuations_Continuation_FrameRecord_primitives = org_graalvm_continuations_Continuation_FrameRecord.requireDeclaredField(
+            org_graalvm_continuations_ContinuationImpl_FrameRecord_primitives = org_graalvm_continuations_ContinuationImpl_FrameRecord.requireDeclaredField(
                             Name.primitives, Type._long_array);
-            org_graalvm_continuations_Continuation_FrameRecord_method = org_graalvm_continuations_Continuation_FrameRecord.requireDeclaredField(
+            org_graalvm_continuations_ContinuationImpl_FrameRecord_method = org_graalvm_continuations_ContinuationImpl_FrameRecord.requireDeclaredField(
                             Name.method, Type.java_lang_reflect_Method);
-            org_graalvm_continuations_Continuation_FrameRecord_next = org_graalvm_continuations_Continuation_FrameRecord.requireDeclaredField(
-                            Name.next, Type.org_graalvm_continuations_Continuation_FrameRecord);
-            org_graalvm_continuations_Continuation_FrameRecord_bci = org_graalvm_continuations_Continuation_FrameRecord.requireDeclaredField(
+            org_graalvm_continuations_ContinuationImpl_FrameRecord_next = org_graalvm_continuations_ContinuationImpl_FrameRecord.requireDeclaredField(
+                            Name.next, Type.org_graalvm_continuations_ContinuationImpl_FrameRecord);
+            org_graalvm_continuations_ContinuationImpl_FrameRecord_bci = org_graalvm_continuations_ContinuationImpl_FrameRecord.requireDeclaredField(
                             Name.bci, Type._int);
             org_graalvm_continuations_IllegalMaterializedRecordException = knownKlass(
                             Type.org_graalvm_continuations_IllegalMaterializedRecordException);

espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/nodes/BytecodeNode.java

@@ -568,7 +568,7 @@ public void createContinuableNode(int bci, int top) {
                 return;
             } else {
                 InstrumentationSupport instrument = instrumentation;
-                int statementIndex = instrument == null ? 0 : instrument.hookBCIToNodeIndex.lookup(0, 0, bs.endBCI());
+                int statementIndex = instrument == null ? 0 : instrument.getStatementIndexAfterJump(0, 0, bs.endBCI());
                 quickenInvoke(top, bci, opcode, statementIndex);
                 // continue loop, will execute at most once more.
             }

espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/nodes/ContinuableMethodWithBytecode.java

@@ -87,7 +87,7 @@ public abstract static class ResumeNextContinuationNode extends EspressoNode {
         @Specialization(guards = "isLastRecord(records)")
         Object doLast(HostFrameRecord records) {
             assert records == null;
-            assert ((EspressoRootNode) getRootNode()).getMethod() == getMeta().continuum.org_graalvm_continuations_Continuation_suspend;
+            assert ((EspressoRootNode) getRootNode()).getMethod() == getMeta().continuum.org_graalvm_continuations_ContinuationImpl_suspend;
             // Was disabled in the call to Continuation.resume0().
             getLanguage().getThreadLocalState().enableSingleStepping();
             return StaticObject.NULL;