Package io.vavr.concurrent

Interface Promise<T>

  • Type Parameters:
    T - The result type of the underlying Future
    public interface Promise<T>
    A Promise is a write-once wrapper around a read-only Future which can complete the underlying Future with a value or an exception.

    The underlying Executor is used to execute asynchronous handlers, e.g. via promise.future().onComplete(...).

    Creation

    Promise offers static factory methods to create new promises which hasn't been fulfilled yet:

    And we may create new promises that are already finished: All the static factory methods mentioned above have additional versions which take an Executor as argument. This gives us more control over thread creation and thread pool sizes.

    One-shot API

    The main purpose of a Promise is to complete its underlying Future. When only a single Thread will eventually complete the Promise, we use one of these methods. Calls will throw if the Promise is already completed.

    API for competing threads

    When multiple Threads may complete our Promise, we typically use one of these methods. Calls will gracefully return false if the Promise is already completed.

    • Method Summary

      Modifier and Type Method Description
      default Promise<T> complete​(Try<? extends T> value)
      Completes this Promise with the given value.
      default Promise<T> completeWith​(Future<? extends T> other)
      Completes this Promise with the given Future, once that Future is completed.
      default java.util.concurrent.Executor executor()
      Returns the Executor used by the underlying Future of this Promise.
      java.util.concurrent.ExecutorService executorService()
      Deprecated.
      Removed starting with Vavr 0.10.0, use executor() instead.
      static <T> Promise<T> failed​(java.lang.Throwable exception)
      Creates a failed Promise, backed by the Future.DEFAULT_EXECUTOR.
      static <T> Promise<T> failed​(java.util.concurrent.Executor executor, java.lang.Throwable exception)
      Creates a failed Promise, backed by the given Executor.
      default Promise<T> failure​(java.lang.Throwable exception)
      Completes this Promise with the given exception.
      static <T> Promise<T> fromTry​(Try<? extends T> result)
      Creates a Promise from a Try, backed by the Future.DEFAULT_EXECUTOR.
      static <T> Promise<T> fromTry​(java.util.concurrent.Executor executor, Try<? extends T> result)
      Creates a Promise from a Try, backed by the given Executor.
      Future<T> future()
      Returns the underlying Future of this Promise.
      default boolean isCompleted()
      Checks if this Promise is completed, i.e.
      static <T> Promise<T> make()
      Makes a Promise that isn't fulfilled yet, backed by the Future.DEFAULT_EXECUTOR.
      static <T> Promise<T> make​(java.util.concurrent.Executor executor)
      Makes a Promise that isn't fulfilled yet, backed by the given Executor.
      static <T> Promise<T> narrow​(Promise<? extends T> promise)
      Narrows a widened Promise<? extends T> to Promise<T> by performing a type-safe cast.
      default Promise<T> success​(T value)
      Completes this Promise with the given value.
      static <T> Promise<T> successful​(java.util.concurrent.Executor executor, T result)
      Creates a succeeded Promise, backed by the given Executor.
      static <T> Promise<T> successful​(T result)
      Creates a succeeded Promise, backed by the Future.DEFAULT_EXECUTOR.
      boolean tryComplete​(Try<? extends T> value)
      Attempts to completes this Promise with the given value.
      default Promise<T> tryCompleteWith​(Future<? extends T> other)
      Attempts to complete this Promise with the specified Future, once that Future is completed.
      default boolean tryFailure​(java.lang.Throwable exception)
      Completes this Promise with the given exception.
      default boolean trySuccess​(T value)
      Completes this Promise with the given value.

    • Method Detail

      • failed

        static <T> Promise<T> failed​(java.lang.Throwable exception)
        Creates a failed Promise, backed by the Future.DEFAULT_EXECUTOR.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        exception - The reason why it failed.
        Returns:
        A failed Promise.
        Throws:
        java.lang.NullPointerException - if exception is null

      • failed

        static <T> Promise<T> failed​(java.util.concurrent.Executor executor,
                             java.lang.Throwable exception)
        Creates a failed Promise, backed by the given Executor.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        executor - An Executor passed to the underlying Future.
        exception - The reason why it failed.
        Returns:
        A failed Promise.
        Throws:
        java.lang.NullPointerException - if executor or exception is null

      • fromTry

        static <T> Promise<T> fromTry​(Try<? extends T> result)
        Creates a Promise from a Try, backed by the Future.DEFAULT_EXECUTOR.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        result - The result.
        Returns:
        A completed Promise which contains either a Success or a Failure.
        Throws:
        java.lang.NullPointerException - if result is null

      • fromTry

        static <T> Promise<T> fromTry​(java.util.concurrent.Executor executor,
                              Try<? extends T> result)
        Creates a Promise from a Try, backed by the given Executor.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        executor - An Executor passed to the underlying Future.
        result - The result.
        Returns:
        A completed Promise which contains either a Success or a Failure.
        Throws:
        java.lang.NullPointerException - if executor or result is null

      • make

        static <T> Promise<T> make()
        Makes a Promise that isn't fulfilled yet, backed by the Future.DEFAULT_EXECUTOR. ForkJoinPool.commonPool().
        Type Parameters:
        T - Result type of the Promise.
        Returns:
        A new Promise.

      • make

        static <T> Promise<T> make​(java.util.concurrent.Executor executor)
        Makes a Promise that isn't fulfilled yet, backed by the given Executor.
        Type Parameters:
        T - Result type of the Promise.
        Parameters:
        executor - An Executor passed to the underlying Future.
        Returns:
        A new Promise.
        Throws:
        java.lang.NullPointerException - if executor is null

      • narrow

        static <T> Promise<T> narrow​(Promise<? extends T> promise)
        Narrows a widened Promise<? extends T> to Promise<T> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.
        Type Parameters:
        T - Component type of the Promise.
        Parameters:
        promise - A Promise.
        Returns:
        the given promise instance as narrowed type Promise<T>.

      • successful

        static <T> Promise<T> successful​(T result)
        Creates a succeeded Promise, backed by the Future.DEFAULT_EXECUTOR.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        result - The result.
        Returns:
        A succeeded Promise.

      • successful

        static <T> Promise<T> successful​(java.util.concurrent.Executor executor,
                                 T result)
        Creates a succeeded Promise, backed by the given Executor.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        executor - An Executor passed to the underlying Future.
        result - The result.
        Returns:
        A succeeded Promise.
        Throws:
        java.lang.NullPointerException - if executor is null

      • executor

        default java.util.concurrent.Executor executor()
        Returns the Executor used by the underlying Future of this Promise.
        Returns:
        The underlying Executor.

      • executorService

        @Deprecated
java.util.concurrent.ExecutorService executorService()
        Deprecated.
        Removed starting with Vavr 0.10.0, use executor() instead.
        This method is deprecated.

        THE DEFAULT IMPLEMENTATION (obtained by one of the Promise factory methods) MIGHT THROW AN UnsupportedOperationException AT RUNTIME, DEPENDING ON WHAT Future.executorService() returns.

        Returns:
        (never)
        Throws:
        java.lang.UnsupportedOperationException - if the underlying Executor isn't an ExecutorService.

      • future

        Future<T> future()
        Returns the underlying Future of this Promise.
        Returns:
        The Future.

      • isCompleted

        default boolean isCompleted()
        Checks if this Promise is completed, i.e. has a value.
        Returns:
        true, if the computation successfully finished or failed, false otherwise.

      • complete

        default Promise<T> complete​(Try<? extends T> value)
        Completes this Promise with the given value.
        Parameters:
        value - Either a Try.Success containing the result or a Try.Failure containing an exception.
        Returns:
        This Promise.
        Throws:
        java.lang.IllegalStateException - if this Promise has already been completed.

      • tryComplete

        boolean tryComplete​(Try<? extends T> value)
        Attempts to completes this Promise with the given value.
        Parameters:
        value - Either a Try.Success containing the result or a Try.Failure containing an exception.
        Returns:
        false if this Promise has already been completed, true otherwise.
        Throws:
        java.lang.IllegalStateException - if this Promise has already been completed.

      • completeWith

        default Promise<T> completeWith​(Future<? extends T> other)
        Completes this Promise with the given Future, once that Future is completed.
        Parameters:
        other - Another Future to react on.
        Returns:
        This Promise.

      • tryCompleteWith

        default Promise<T> tryCompleteWith​(Future<? extends T> other)
        Attempts to complete this Promise with the specified Future, once that Future is completed.
        Parameters:
        other - Another Future to react on.
        Returns:
        This Promise.

      • success

        default Promise<T> success​(T value)
        Completes this Promise with the given value.
        Parameters:
        value - A value.
        Returns:
        This Promise.
        Throws:
        java.lang.IllegalStateException - if this Promise has already been completed.

      • trySuccess

        default boolean trySuccess​(T value)
        Completes this Promise with the given value.
        Parameters:
        value - A value.
        Returns:
        false if this Promise has already been completed, true otherwise.

      • failure

        default Promise<T> failure​(java.lang.Throwable exception)
        Completes this Promise with the given exception.
        Parameters:
        exception - An exception.
        Returns:
        This Promise.
        Throws:
        java.lang.IllegalStateException - if this Promise has already been completed.

      • tryFailure

        default boolean tryFailure​(java.lang.Throwable exception)
        Completes this Promise with the given exception.
        Parameters:
        exception - An exception.
        Returns:
        false if this Promise has already been completed, true otherwise.