Package de.esoco.coroutine

Class Suspension<T>

  • Direct Known Subclasses:
    Selection
    public class Suspension<T>
extends java.lang.Object
    Encapsulates the data that represents a suspended Coroutine. The execution can be resumed by invoking resume().

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void cancel()
      Cancels this suspension.
      Continuation<?> continuation()
      Returns the continuation of the suspended coroutine.
      void fail​(java.lang.Throwable error)
      Cancels this suspension because of an error.
      void ifNotCancelled​(java.lang.Runnable code)
      Executes code only if this suspension has not (yet) been cancel.
      boolean isCancelled()
      Checks if the this suspension has been cancelled.
      void onCancel​(de.esoco.lib.expression.monad.Option<java.lang.Runnable> cancelHandler)
      Sets an optional handler to be invoked if this suspension is cancelled.
      void resume()
      Resumes the execution of the suspended coroutine with the input value provided to the constructor.
      void resume​(T value)
      Resumes the execution of the suspended coroutine with the given value.
      CoroutineStep<?,​T> suspendingStep()
      Returns the suspending step.
      java.lang.String toString()
      T value()
      Returns the value of this suspension.
      Suspension<T> withValue​(T value)
      Sets the suspension value and returns this instance so that it can be used as an updated argument to method calls.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • Suspension

        protected Suspension​(CoroutineStep<?,​T> suspendingStep,
                     CoroutineStep<T,​?> resumeStep,
                     Continuation<?> continuation)
        Creates a new instance. The input value for the resume step is not provided here because it is typically not available upon suspension because it will only become available when the suspension is resumed (e.g. when receiving data). To resume execution with an explicit input value the method resume(Object) can be used. If the resume should occur at a different time than the availability of the input value a suspension can be updated by calling withValue(Object). In that case resume() can be used later to resume the execution.
        Parameters:
        suspendingStep - The step that initiated the suspension
        resumeStep - The step to resume the execution with
        continuation - The continuation of the execution

    • Method Detail

      • cancel

        public void cancel()
        Cancels this suspension. This will cancel the continuation. Tries to resume a cancelled suspension will be ignored. If a cancel handler has been registered with onCancel(Option) it will be invoked.

      • continuation

        public final Continuation<?> continuation()
        Returns the continuation of the suspended coroutine.
        Returns:
        The continuation

      • fail

        public void fail​(java.lang.Throwable error)
        Cancels this suspension because of an error. This will fail the continuation. Tries to resume a failed suspension will be ignored.
        Parameters:
        error - The error exception

      • ifNotCancelled

        public void ifNotCancelled​(java.lang.Runnable code)
        Executes code only if this suspension has not (yet) been cancel. The given code will be executed with a lock on the cancelation state to prevent race conditions if other threads try to cancel a suspension while it is resumed.
        Parameters:
        code - The code to execute only if this suspension is not cancelled

      • isCancelled

        public final boolean isCancelled()
        Checks if the this suspension has been cancelled.
        Returns:
        TRUE if the suspension has been cancelled

      • onCancel

        public void onCancel​(de.esoco.lib.expression.monad.Option<java.lang.Runnable> cancelHandler)
        Sets an optional handler to be invoked if this suspension is cancelled. Only one handler at a time is supported, setting a new one will replace any previously registered handler.
        Parameters:
        cancelHandler - The optional cancel handler

      • resume

        public final void resume()
        Resumes the execution of the suspended coroutine with the input value provided to the constructor.
        See Also:
        resume(Object)

      • resume

        public void resume​(T value)
        Resumes the execution of the suspended coroutine with the given value.
        Parameters:
        value - The input value to the resumed step

      • suspendingStep

        public final CoroutineStep<?,​T> suspendingStep()
        Returns the suspending step.
        Returns:
        The suspending step

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • value

        public final T value()
        Returns the value of this suspension. The value will be used as the input of the resumed step.
        Returns:
        The suspension value

      • withValue

        public Suspension<T> withValue​(T value)
        Sets the suspension value and returns this instance so that it can be used as an updated argument to method calls.
        Parameters:
        value - The new value
        Returns:
        This instance