Serializable
public abstract class Continuation extends Object implements Serializable
A Continuation
object is an immutable object that captures everything in
the Java stack. This includes
(1) current instruction pointer,
(2) return addresses, and
(3) local variables.
Continuation
objects are used to restore the captured execution states
later.
Modifier and Type | Method | Description |
---|---|---|
static void |
again() |
Jumps to where the execution was resumed.
|
static void |
cancel() |
Jumps to where the execution was resumed, and suspend execution.
|
static Continuation |
continueWith(Continuation continuation) |
Deprecated.
|
static Continuation |
continueWith(Continuation continuation,
Object value) |
Deprecated.
|
static void |
exit() |
Completes the execution of the running continuation.
|
static Object |
getContext() |
get the current context.
|
boolean |
isSerializable() |
Check if captured continuation is serializable
|
abstract Continuation |
multiShot() |
View this continuation as a "multi-shot" continuation that may be resumed multiple times.
|
Continuation |
resume() |
Resumes the execution of the specified continuation from where it's left off.
|
Continuation |
resume(Object value) |
Resumes the execution of the specified continuation from where it's left off
and creates a new continuation representing the new state.
|
protected abstract Continuation |
resumeWith(ResumeParameter param) |
|
abstract Continuation |
singleShot() |
View this continuation as a performance-optimized continuation that may be resumed only once.
|
static Continuation |
startSuspendedWith(Runnable target) |
Creates a new
Continuation object from the specified Runnable
object. |
static Continuation |
startSuspendedWith(Runnable target,
boolean singleShot) |
Creates a new
Continuation object from the specified Runnable
object. |
static Continuation |
startWith(Runnable target) |
|
static Continuation |
startWith(Runnable target,
boolean singleShot) |
|
static Continuation |
startWith(Runnable target,
Object context) |
|
static Continuation |
startWith(Runnable target,
Object context,
boolean singleShot) |
|
static Object |
suspend() |
Stops the running continuation.
|
static Object |
suspend(Object value) |
Stops the running continuation.
|
void |
terminate() |
Abnormally terminates the suspended call chain represented by this continuation.
|
String |
toString() |
|
Object |
value() |
Accessor for value yielded by continuation
|
public static Object getContext()
This method returns the same context object given to startWith(Runnable, Object)
or resume(Object)
.
A different context can be used for each run of a continuation, so this mechanism can be used to associate some state with each execution.
NullPointerException
- if this method is invoked outside startWith(Runnable, Object)
or resume(Object)
.public static Continuation startSuspendedWith(Runnable target)
Continuation
object from the specified Runnable
object.
Unlike the startWith(Runnable)
method, this method doesn't actually
execute the Runnable
object. It will be executed when
it's resumed
.
target
- The object whose run
method will be executed.public static Continuation startSuspendedWith(Runnable target, boolean singleShot)
Continuation
object from the specified Runnable
object.
Unlike the startWith(Runnable)
method, this method doesn't actually
execute the Runnable
object. It will be executed when
it's resumed
.
target
- The object whose run
method will be executed.singleShot
- If true then continuation constructed is performance-optimized but
may be resumed only once. Otherwise "multi-shot" continuation is created that may
be resumed multiple times.public static Continuation startWith(Runnable target)
Runnable
object in an environment
that allows suspend()
.
This is a short hand for startWith(target,null)
.
target
- The object whose run
method will be executed.null
startWith(Runnable, Object)
public static Continuation startWith(Runnable target, boolean singleShot)
Runnable
object in an environment
that allows suspend()
.
This is a short hand for startWith(target,null)
.
target
- The object whose run
method will be executed.singleShot
- If true then continuation constructed is performance-optimized but
may be resumed only once. Otherwise "multi-shot" continuation is created that may
be resumed multiple times.null
startWith(Runnable, Object)
public static Continuation startWith(Runnable target, Object context)
Runnable
object in an environment
that allows suspend()
.
This method blocks until the continuation suspends or completes.target
- The object whose run
method will be executed.context
- This value can be obtained from getContext()
until this method returns.
Can be null.suspended
, in which case
a new non-null continuation is returned.getContext()
public static Continuation startWith(Runnable target, Object context, boolean singleShot)
Runnable
object in an environment
that allows suspend()
.
This method blocks until the continuation suspends or completes.target
- The object whose run
method will be executed.context
- This value can be obtained from getContext()
until this method returns.
Can be null.singleShot
- If true then continuation constructed is performance-optimized but
may be resumed only once. Otherwise "multi-shot" continuation is created that may
be resumed multiple times.suspended
, in which case
a new non-null continuation is returned.getContext()
public static Continuation continueWith(Continuation continuation)
resume()
instead
Resumes the execution of the specified continuation from where it's left off.
This is a short hand for continueWith(resumed,null)
.
continuation
- The suspended continuation to be resumed. Must not be null.suspended
, in which case
a new non-null continuation is returned.continueWith(Continuation, Object)
public static Continuation continueWith(Continuation continuation, Object value)
resume(Object)
instead
Resumes the execution of the specified continuation from where it's left off
and creates a new continuation representing the new state.
This method blocks until the continuation suspends or completes.continuation
- The suspended continuation to be resumed. Must not be null.value
- The value to be returned as a result form Continuation.suspend()
call or
from getContext()
until this method returns. Can be null.suspended
, in which case
a new non-null continuation is returned.getContext()
,
suspend()
public Continuation resume()
This is a short hand for resume(null)
.
suspended
, in which case
a new non-null continuation is returned.resume(Object)
public Continuation resume(Object value)
value
- The value to be returned as a result form Continuation.suspend()
call or
from getContext()
until this method returns. Can be null.suspended
, in which case
a new non-null continuation is returned.getContext()
,
suspend()
public void terminate()
Use this method to execute any clean-up code of suspended methods (finally
blocks)
when there is no need to resume()
the continuation.
public boolean isSerializable()
public Object value()
suspend(Object)
public abstract Continuation multiShot()
View this continuation as a "multi-shot" continuation that may be resumed multiple times.
Conversion to the multi-shot continuation is not always possible, i.e. already resumed single-shot continuation may not be converted to the multi-shot variant.
public abstract Continuation singleShot()
View this continuation as a performance-optimized continuation that may be resumed only once.
Conversion to the single-shot continuation is always possible
public static Object suspend()
This method can be only called inside resume()
or startWith(java.lang.Runnable)
methods.
When called, the thread returns from the above methods with a new Continuation
object that captures the thread state.
resume(Object)
and is identical to value returned by getContext()
.IllegalStateException
- if this method is called outside the resume()
or startWith(java.lang.Runnable)
methods.public static Object suspend(Object value)
This method can be only called inside continueWith(org.apache.commons.javaflow.api.Continuation)
or startWith(java.lang.Runnable)
methods.
When called, the thread returns from the above methods with a new Continuation
object that captures the thread state and with value()
equals to parameter passed.
value
- The intermediate result yielded by suspended continuations
The value may be accessed via value()
method of continuation returnedgetContext()
.IllegalStateException
- if this method is called outside the continueWith(org.apache.commons.javaflow.api.Continuation)
or startWith(java.lang.Runnable)
methods.public static void exit()
This method can be only called inside continueWith(org.apache.commons.javaflow.api.Continuation)
or startWith(java.lang.Runnable)
methods.
When called, the thread returns from the above methods with null,
indicating that there's nothing more to continue.
This method is similiar to how System.exit(int)
works for JVM.
public static void again()
This method can be only called inside continueWith(org.apache.commons.javaflow.api.Continuation)
or startWith(java.lang.Runnable)
methods.
When called, the execution jumps to where it was resumed
(if the execution has never resumed before, from the beginning
of Runnable.run()
.)
Consider the following example:
Continuation.suspend(); System.out.println("resumed"); r = new Random().nextInt(5); if(r!=0) { System.out.println("do it again"); Continuation.again(); } System.out.println("done");
This program produces an output like this (the exact number of 'do it again' depends on each execution, as it's random.)
resumed do it again resumed do it again resumed do it again resumed done
The calling startWith(Runnable)
method and
continueWith(Continuation)
method does not
return when a program running inside uses this method.
public static void cancel()
This method almost works like the again()
method,
but instead of re-executing, this method first suspends the execution.
Therefore,
the calling startWith(Runnable)
method and
continueWith(Continuation)
method
return when a program running inside uses this method.
protected abstract Continuation resumeWith(ResumeParameter param)
Copyright © 2022. All rights reserved.