Package org.apache.commons.javaflow.api

Class Continuation

  • All Implemented Interfaces:
    Serializable
    public abstract class Continuation
extends Object
implements Serializable
    Snapshot of a thread execution state.

    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.

    See Also:
    Serialized Form

    • Method Detail

      • startSuspendedWith

        public static Continuation startSuspendedWith​(Runnable target)
        Creates a new 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.

        Parameters:
        target - The object whose run method will be executed.
        Returns:
        always return a non-null valid object.

      • startSuspendedWith

        public static Continuation startSuspendedWith​(Runnable target,
                                              boolean singleShot)
        Creates a new 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.

        Parameters:
        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.
        Returns:
        always return a non-null valid object.

      • startWith

        public static Continuation startWith​(Runnable target)
        Starts executing the specified Runnable object in an environment that allows suspend().

        This is a short hand for startWith(target,null).

        Parameters:
        target - The object whose run method will be executed.
        Returns:
        Continuation object if runnable supplied is supended, otherwise null
        See Also:
        startWith(Runnable, Object)

      • startWith

        public static Continuation startWith​(Runnable target,
                                     boolean singleShot)
        Starts executing the specified Runnable object in an environment that allows suspend().

        This is a short hand for startWith(target,null).

        Parameters:
        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.
        Returns:
        Continuation object if runnable supplied is supended, otherwise null
        See Also:
        startWith(Runnable, Object)

      • startWith

        public static Continuation startWith​(Runnable target,
                                     Object context)
        Starts executing the specified Runnable object in an environment that allows suspend(). This method blocks until the continuation suspends or completes.
        Parameters:
        target - The object whose run method will be executed.
        context - This value can be obtained from getContext() until this method returns. Can be null.
        Returns:
        If the execution completes and there's nothing more to continue, return null. Otherwise, the execution has been suspended, in which case a new non-null continuation is returned.
        See Also:
        getContext()

      • startWith

        public static Continuation startWith​(Runnable target,
                                     Object context,
                                     boolean singleShot)
        Starts executing the specified Runnable object in an environment that allows suspend(). This method blocks until the continuation suspends or completes.
        Parameters:
        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.
        Returns:
        If the execution completes and there's nothing more to continue, return null. Otherwise, the execution has been suspended, in which case a new non-null continuation is returned.
        See Also:
        getContext()

      • continueWith

        public static Continuation continueWith​(Continuation continuation)
        Deprecated.
        This method is deprecated, please use resume() instead Resumes the execution of the specified continuation from where it's left off.

        This is a short hand for continueWith(resumed,null).

        Parameters:
        continuation - The suspended continuation to be resumed. Must not be null.
        Returns:
        If the execution completes and there's nothing more to continue, return null. Otherwise, the execution has been suspended, in which case a new non-null continuation is returned.
        See Also:
        continueWith(Continuation, Object)

      • continueWith

        public static Continuation continueWith​(Continuation continuation,
                                        Object value)
        Deprecated.
        This method is deprecated, please use 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.
        Parameters:
        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.
        Returns:
        If the execution completes and there's nothing more to continue, return null. Otherwise, the execution has been suspended, in which case a new non-null continuation is returned.
        See Also:
        getContext(), suspend()

      • resume

        public Continuation resume()
        Resumes the execution of the specified continuation from where it's left off.

        This is a short hand for resume(null).

        Returns:
        If the execution completes and there's nothing more to continue, return null. Otherwise, the execution has been suspended, in which case a new non-null continuation is returned.
        See Also:
        resume(Object)

      • resume

        public 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. This method blocks until the continuation suspends or completes.
        Parameters:
        value - The value to be returned as a result form Continuation.suspend() call or from getContext() until this method returns. Can be null.
        Returns:
        If the execution completes and there's nothing more to continue, return null. Otherwise, the execution has been suspended, in which case a new non-null continuation is returned.
        See Also:
        getContext(), suspend()

      • terminate

        public void terminate()
        Abnormally terminates the suspended call chain represented by this continuation.

        Use this method to execute any clean-up code of suspended methods (finally blocks) when there is no need to resume() the continuation.

      • isSerializable

        public boolean isSerializable()
        Check if captured continuation is serializable
        Returns:
        true if all variables on captured stack and runnable supplied are serializeble, false otherwise.

      • value

        public Object value()
        Accessor for value yielded by continuation
        Returns:
        The latest value yielded by suspended continuation. The value is passed from the continuation to the client code via suspend(Object)

      • multiShot

        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.

        Returns:
        self if this is already a multi-shot continuation or a newly constructed multi-shot continuation

      • singleShot

        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

        Returns:
        self if this is already a single-shot continuation or a newly constructed single-shot continuation

      • again

        public static void again()
        Jumps to where the execution was resumed.

        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.

      • cancel

        public static void cancel()
        Jumps to where the execution was resumed, and suspend execution.

        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.