Package dev.gmitch215.bytebox.locks

Class CompletableFuture<T>

java.lang.Object
dev.gmitch215.bytebox.locks.CompletableFuture<T>
Type Parameters:
T - the value type
All Implemented Interfaces:
CompletionStage<T>, Future<T>
public class CompletableFuture<T> extends Object implements Future<T>, CompletionStage<T>
java.util.concurrent.CompletableFuture, which the class library does not carry.

Failures follow the JDK's wrapping: a stage that fails because of another is completed with a CompletionException around the cause, join() throws that, and get() unwraps it into an ExecutionException. supplyAsync(Supplier) runs the task on a new fiber, since there is no pool, and callbacks run on the fiber that completes the stage.

get(), get(long, TimeUnit) and join() suspend the caller, so they trap when no fiber is running, even on a future that is already done. The generated entry point builds the handler, a Durable Object and a Workflow on a fiber, so their constructors and the static initializers they trigger may call them.

When a whenComplete action throws on a stage that had already failed, the original failure stands and the action's is dropped; the JDK adds it as a suppressed exception, and Throwable.addSuppressed throws a NullPointerException on this runtime.

Left out: the *Async forms of the then methods, the *Either and *Both forms, orTimeout, completeAsync, the obtrude methods and the Java 19 additions. Calling one fails to link when the program is built.

Since:
1.0.3

  • Constructor Details

    • CompletableFuture

      public CompletableFuture()
      A future nothing has completed.

  • Method Details

    • supplyAsync

      public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier)
      Type Parameters:
      U - the value type
      Parameters:
      supplier - computes the value on a new fiber
      Returns:
      the future its result completes

    • supplyAsync

      public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier, Executor executor)
      Type Parameters:
      U - the value type
      Parameters:
      supplier - computes the value
      executor - runs the task
      Returns:
      the future its result completes

    • runAsync

      public static CompletableFuture<Void> runAsync(Runnable runnable)
      Parameters:
      runnable - runs on a new fiber
      Returns:
      the future that completes once it has run

    • runAsync

      public static CompletableFuture<Void> runAsync(Runnable runnable, Executor executor)
      Parameters:
      runnable - runs
      executor - runs the task
      Returns:
      the future that completes once it has run

    • completedFuture

      public static <U> CompletableFuture<U> completedFuture(U value)
      Type Parameters:
      U - the value type
      Parameters:
      value - the value
      Returns:
      a future already holding it

    • failedFuture

      public static <U> CompletableFuture<U> failedFuture(Throwable ex)
      Type Parameters:
      U - the value type
      Parameters:
      ex - the failure
      Returns:
      a future already failed with it

    • allOf

      public static CompletableFuture<Void> allOf(CompletableFuture<?>... cfs)
      Parameters:
      cfs - the futures to wait for
      Returns:
      a future that completes once all of them have, failing with the first failure in argument order

    • anyOf

      public static CompletableFuture<Object> anyOf(CompletableFuture<?>... cfs)
      Parameters:
      cfs - the futures to race
      Returns:
      a future that completes with whichever finishes first, the first listed when several already have; one that never completes when none are given

    • complete

      public boolean complete(T value)
      Parameters:
      value - the value
      Returns:
      whether this call completed the future

    • completeExceptionally

      public boolean completeExceptionally(Throwable ex)
      Parameters:
      ex - the failure
      Returns:
      whether this call completed the future

    • cancel

      public boolean cancel(boolean mayInterruptIfRunning)
      Specified by:
      cancel in interface Future<T>
      Parameters:
      mayInterruptIfRunning - ignored
      Returns:
      whether the future is now cancelled

    • isDone

      public boolean isDone()
      Returns whether the future has a result, a failure or was cancelled.
      Specified by:
      isDone in interface Future<T>
      Returns:
      whether the future has a result, a failure or was cancelled

    • isCancelled

      public boolean isCancelled()
      Returns whether the future was cancelled.
      Specified by:
      isCancelled in interface Future<T>
      Returns:
      whether the future was cancelled

    • isCompletedExceptionally

      public boolean isCompletedExceptionally()
      Returns whether the future failed, including by cancellation.
      Returns:
      whether the future failed, including by cancellation

    • get

      public T get() throws InterruptedException, ExecutionException
      Suspends the caller until the future is done.
      Specified by:
      get in interface Future<T>
      Returns:
      the value
      Throws:
      InterruptedException - if the caller was interrupted while waiting
      ExecutionException - if the future failed, with the underlying failure as its cause

    • get

      public T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
      Specified by:
      get in interface Future<T>
      Parameters:
      timeout - the longest to wait
      unit - the unit of timeout
      Returns:
      the value
      Throws:
      InterruptedException - if the caller was interrupted while waiting
      ExecutionException - if the future failed, with the underlying failure as its cause
      TimeoutException - if the time ran out first

    • join

      public T join()
      Suspends the caller until the future is done.
      Returns:
      the value
      Throws:
      CompletionException - if the future failed, with the underlying failure as its cause

    • getNow

      public T getNow(T valueIfAbsent)
      Parameters:
      valueIfAbsent - returned when the future is not done
      Returns:
      the value, or valueIfAbsent

    • thenApply

      public <U> CompletableFuture<U> thenApply(Function<? super T,? extends U> fn)
      Specified by:
      thenApply in interface CompletionStage<T>
      Type Parameters:
      U - the mapped type
      Parameters:
      fn - maps the value
      Returns:
      a stage holding the mapped value

    • thenAccept

      public CompletableFuture<Void> thenAccept(Consumer<? super T> action)
      Specified by:
      thenAccept in interface CompletionStage<T>
      Parameters:
      action - takes the value
      Returns:
      a stage that completes once the action has run

    • thenRun

      public CompletableFuture<Void> thenRun(Runnable action)
      Specified by:
      thenRun in interface CompletionStage<T>
      Parameters:
      action - runs once this stage completes normally
      Returns:
      a stage that completes once the action has run

    • thenCombine

      public <U, V> CompletableFuture<V> thenCombine(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
      Specified by:
      thenCombine in interface CompletionStage<T>
      Type Parameters:
      U - the second value type
      V - the combined type
      Parameters:
      other - the second stage
      fn - combines both values
      Returns:
      a stage holding the combined value

    • thenCompose

      public <U> CompletableFuture<U> thenCompose(Function<? super T,? extends CompletionStage<U>> fn)
      Specified by:
      thenCompose in interface CompletionStage<T>
      Type Parameters:
      U - the adopted type
      Parameters:
      fn - returns the stage whose result this one adopts
      Returns:
      a stage holding that result

    • exceptionally

      public CompletableFuture<T> exceptionally(Function<Throwable,? extends T> fn)
      Specified by:
      exceptionally in interface CompletionStage<T>
      Parameters:
      fn - turns a failure into a value
      Returns:
      a stage holding the value or the recovered one

    • handle

      public <U> CompletableFuture<U> handle(BiFunction<? super T,Throwable,? extends U> fn)
      Specified by:
      handle in interface CompletionStage<T>
      Type Parameters:
      U - the mapped type
      Parameters:
      fn - maps the value and the failure, one of which is null
      Returns:
      a stage holding the mapped value

    • whenComplete

      public CompletableFuture<T> whenComplete(BiConsumer<? super T,? super Throwable> action)
      Specified by:
      whenComplete in interface CompletionStage<T>
      Parameters:
      action - sees the value and the failure, one of which is null
      Returns:
      a stage with this one's result

    • toCompletableFuture

      public CompletableFuture<T> toCompletableFuture()
      Description copied from interface: CompletionStage
      Returns this stage as a CompletableFuture.
      Specified by:
      toCompletableFuture in interface CompletionStage<T>
      Returns:
      this stage as a CompletableFuture

    • toString

      public String toString()
      Overrides:
      toString in class Object