Restructure text

Author: spkrka

Diff for: README.md

@@ -0,0 +1,87 @@
+# The Java 8 API
+CompletableFuture has the following static methods:
+* `supplyAsync(Supplier<T>)` and `supplyAsync(Supplier<T>, Executor)` - Create a future from code that runs on a different thread 
+* `runAsync(Runnable, Executor)` and `runAsync(Runnable)` - Similar to supplyAsync, but returns a void future
+* `completedFuture(T)` - Returns a future that's already complete
+* `allOf(CompletableFuture...)` - A future that completes when all futures complete  
+* `anyOf(CompletableFuture...)` - Similar to allOf, but returns as soon as any of the futures complete
+
+Methods for introspecting the state of a future:
+* `isDone()`, `isCancelled()` and `isCompletedExceptionally()` - Self-explanatory? 
+* `getNumberOfDependents()` - Estimated number of callbacks for future completion (For monitoring only!) 
+
+Methods for extracting the value of a future:
+* `getNow(T default)` - Non-blocking - returns the default value if it is not complete. 
+* `get()` - Blocking get - throws checked exceptions
+* `get(long, TimeUnit)` - Blocking get, but with a timeout
+* `join()` - Blocking get - throws unchecked exceptions 
+
+Methods for setting the state of the future
+* `complete(Object)`, `completeExceptionally(Throwable)` and `cancel(boolean)` - Complete the future in various ways 
+* `obtrudeValue(Object)` and `obtrudeException(Throwable)` - Complete the future, mutating the value it even if it is already completed! 
+
+It has a bunch of methods that operate on a future to create a new (and improved!) future:
+* `thenApply(Function)` - transform value -> value
+* `thenApplyAsync(Function, Executor)` - 
+* `thenApplyAsync(Function)` - 
+* `thenAccept(Consumer)` - 
+* `thenAcceptAsync(Consumer, Executor)` - 
+* `thenAcceptAsync(Consumer)` - 
+* `thenRun(Runnable)` - 
+* `thenRunAsync(Runnable, Executor)` - 
+* `thenRunAsync(Runnable)` - 
+* `thenCombine(CompletionStage, BiFunction)` - 
+* `thenCombineAsync(CompletionStage, BiFunction, Executor)` - 
+* `thenCombineAsync(CompletionStage, BiFunction)` - 
+* `thenAcceptBoth(CompletionStage, BiConsumer)` - 
+* `thenAcceptBothAsync(CompletionStage, BiConsumer, Executor)` - 
+* `thenAcceptBothAsync(CompletionStage, BiConsumer)` - 
+* `runAfterBoth(CompletionStage, Runnable)` - 
+* `runAfterBothAsync(CompletionStage, Runnable, Executor)` - 
+* `runAfterBothAsync(CompletionStage, Runnable)` - 
+* `applyToEither(CompletionStage, Function)` - 
+* `applyToEitherAsync(CompletionStage, Function, Executor)` - 
+* `applyToEitherAsync(CompletionStage, Function)` - 
+* `acceptEither(CompletionStage, Consumer)` - 
+* `acceptEitherAsync(CompletionStage, Consumer, Executor)` - 
+* `acceptEitherAsync(CompletionStage, Consumer)` - 
+* `runAfterEither(CompletionStage, Runnable)` - 
+* `runAfterEitherAsync(CompletionStage, Runnable, Executor)` - 
+* `runAfterEitherAsync(CompletionStage, Runnable)` - 
+* `thenCompose(Function)` - transform value -> CompletionStage(value)
+* `thenComposeAsync(Function, Executor)` - 
+* `thenComposeAsync(Function)` - 
+* `whenComplete(BiConsumer)` - 
+* `whenCompleteAsync(BiConsumer, Executor)` - 
+* `whenCompleteAsync(BiConsumer)` - 
+* `handle(BiFunction)` - transform either value or exception
+* `handleAsync(BiFunction, Executor)` - 
+* `handleAsync(BiFunction)` - 
+* `exceptionally(Function)` - transform exception
+
+There are a lot of methods here - most of them can be expressed in terms of `handle` and `thenCompose`
+and can be considered convenience methods and to better express intent.
+
+Some of them can be considered callbacks instead of transforms, but they still return futures so you can
+take actions on the completion, even if you don't care about their values. 
+
+# News in Java 9
+
+With Java 9 we got some additions to the API.
+
+New static methods:
+* `delayedExecutor(long, TimeUnit)` and `delayedExecutor(long, TimeUnit, Executor)` - Get an executor that delays the work 
+* `completedStage(Object)`, `failedFuture(Throwable)` and `failedStage(Throwable)` - Complements for the `completedFuture(Object)` method 
+
+New instance methods:
+* `newIncompleteFuture()` - Virtual constructor, intended for subclassing
+* `defaultExecutor()` - Get the default executor that is used for default `*Async` transforms.
+* `copy()` - Convenience method for `thenApply(x -> x)`
+* `minimalCompletionStage()` - Returns a more restricted future 
+* `completeAsync(Supplier, Executor)` and `completeAsync(Supplier)` - Complete the future using a supplier 
+* `completeOnTimeout(Object, long, TimeUnit)` - Complete the future with a value after a timeout
+* `orTimeout(long, TimeUnit)` - Complete the future with an exception after a timeout
+
+# Changes between Java 10 and Java 15
+
+Nothing has changed - this API seems to have stabilized.

Diff for: api.md

@@ -0,0 +1,20 @@
+The concept of futures is not limited to asynchronous programming in Java.
+This [wikipedia article](https://en.wikipedia.org/wiki/Futures_and_promises) has more details about it.
+
+## Producers and consumers
+
+You can think of futures from two sides - producers and consumers.
+
+We usually spend most of the time using futures as consumers, and then we usually seem them as read-only containers
+that change state once. We can subscribe to be notified when the state changes and trigger further work.
+
+From a producer side, we should instead use the term Promise. You create a _promise_ that you will produce a value
+and some time later when the value is ready, you complete or fulfill the promise. The future associated with the promise
+will thus complete and the consumer can act on it.
+
+You can think of it as the following flow:
+* The producer creates a Promise
+* The produces extracts the Future from the Promise and gives the Future to the consumer.
+* The consumer starts registering callbacks and transformations on the future.
+* At some point later the producer fulfills the Promise and the callbacks will trigger for the consumer. 
+

Diff for: futures-concept.md

@@ -0,0 +1,25 @@
+# A brief history of futures in Java
+
+Java 1.5 introduced the `Future` interface but it was a very limited - you could call `get()` and `isDone()`
+but there was no way to get notified of state changes. Instead you would need to do polling.
+
+Google Guava introduced the `ListenableFuture` interface which extends `Future` but also adds
+`addListener(Runnable, executor)` - this one method enabled a more asynchronous development model.
+All other useful methods could now be implemented as utility functions on top of the primitives.
+
+The Google Guava class `Futures` included some very useful methods:
+* `addCallback(callback)` - convenience method on top of `addListener`
+* `transform(function)` - return a new future after applying a function to the values
+* `transformAsync(function)` - like transform, but the function should return a future instead.
+  (Similar to Java 8 `thenCompose`)
+
+Then with Java 8 we got `CompletableFuture` which had achieved feature parity with Google Guava futures,
+though with differences in:
+* Fluent API - `CompletableFuture` has a fluent API unlike `ListenableFuture` (but Google later added `FluentFuture` too)
+* Mutability - Google futures separates the producer side from the consumer side, while they are much more tightly coupled
+  in `CompletableFuture`.
+* Number of primitives - Google futures have a small set of primitives (transform, transformAsync, catching) that
+  can be combined while `CompletableFuture` has a large set of methods for combinations of the underlying primitives.
+  thenApply, thenRun and thenAccept could be reduced to a single promitive and likewise for
+  handle, runAfter, runAsync, whenComplete. Almost all methods in `CompletableFuture` also exist in three variants:
+  regular, async with default executor and async with custom executor.   

Diff for: history.md

@@ -0,0 +1,39 @@
+# Completable-futures library
+
+To simplify life working with Java 8+ futures, there's a Spotify library called
+[completable-futures](https://github.com/spotify/completable-futures).
+
+It contains some useful utility methods, described in more detail below
+
+## dereference
+
+Sometimes (through no fault of you own, I'm sure!) you may end up with something like:
+`CompletableFuture<CompletableFuture<T>> future` which may be annoying to work with.
+
+Fortunately, it's not very difficult to convert that to `CompletableFuture<T> future2`.
+All you need to do is apply `thenCompose(value -> value)` (composing with the identity function).
+
+This has been wrapped as `dereference` - naming was chosen to correspond to the equivalent function in Google Guava.
+
+## getCompleted and getException
+
+These functions can simplify getting the value or exception from a completed future, without risking blocking the thread.
+
+This is typically useful in code that needs the value from known completed futures or in unit tests.
+
+## exceptionallyCompose
+
+`exceptionallyCompose()` was introduced to cover the usecase of handling a failure by doing more asynchronous work.
+While the Java 8 API lets you handle a successful future and compose it (with `thenCompose`) there is no such
+ equivalent for handling exception. This convenience method is very simple to implement.
+
+> **_Implementation:_** [ExceptionallyCompose](src/test/java/se/krka/futures/ExceptionallyCompose.java)
+
+## combine
+
+It also includes some utility functions to combine multiple futures in a safe way, avoiding manual error-prone calls
+to get or join. 
+
+## And more...
+
+Check out the github page to learn about more utilities.

Diff for: library.md

@@ -0,0 +1,82 @@
+package se.krka.futures;
+
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.function.Consumer;
+import java.util.function.Function;
+
+public class PFuture<T> {
+  private final CompletableFuture<T> future;
+
+  PFuture(CompletableFuture<T> future) {
+    this.future = future;
+  }
+
+  public <R> PFuture<R> map(Function<T, R> function) {
+    return new PFuture<>(future.thenApply(function));
+  }
+
+  public PFuture<T> tap(Consumer<T> function) {
+    return new PFuture<>(future.thenApply(t -> {
+      function.accept(t);
+      return t;
+    }));
+  }
+
+  public <R> PFuture<R> flatMap(Function<T, PFuture<R>> function) {
+    return new PFuture<>(future.thenCompose(t -> function.apply(t).future));
+  }
+
+  public static <R> PFuture<R> flatten(PFuture<PFuture<R>> future) {
+    return new PFuture<>(future.future.thenCompose(v -> v.future));
+  }
+
+  public boolean isDone() {
+    return future.isDone();
+  }
+
+  public boolean isCompletedExceptionally() {
+    return future.isCompletedExceptionally();
+  }
+
+  public boolean isCompletedNormally() {
+    return future.isDone() && !future.isCompletedExceptionally();
+  }
+
+
+  public Throwable getException() {
+    if (isCompletedExceptionally()) {
+      try {
+        T value = future.join();
+        assert value != null;
+      } catch (CancellationException e) {
+        return e;
+      } catch (CompletionException e) {
+        return e.getCause();
+      }
+      throw new IllegalStateException("Unreachable code");
+    } else {
+      throw new IllegalStateException("Future does not have an exception");
+    }
+  }
+
+  public T getValue() {
+    if (isCompletedNormally()) {
+      return future.join();
+    } else {
+      throw new IllegalStateException("Future does not have a value");
+    }
+  }
+
+  @Override
+  public String toString() {
+    if (isCompletedExceptionally()) {
+      return "PFuture(exception=" + getException().getMessage() + ")";
+    } else if (isCompletedNormally()) {
+      return "PFuture(value=" + getValue() + ")";
+    } else {
+      return "PFuture(incomplete)";
+    }
+  }
+}

Diff for: src/main/java/se/krka/futures/PFuture.java

@@ -29,7 +29,7 @@ public void cancel() {
     producerFuture.cancel(false);
   }
 
-  public CompletableFuture<T> getFuture() {
-    return producerFuture.thenApply(Function.identity());
+  public PFuture<T> getFuture() {
+    return new PFuture<>(producerFuture);
   }
 }

Diff for: src/main/java/se/krka/futures/Promise.java

@@ -7,6 +7,7 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
 
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertTrue;
 
@@ -15,13 +16,17 @@ public class CancelTest {
   public void cancelSimple() {
     CompletableFuture<?> future = new CompletableFuture<>();
     future.cancel(true);
+
+    assertEquals(CancellationException.class, Util.exceptionFromCallback(future).getClass());
     Util.assertException(future, List.of(CancellationException.class));
   }
 
   @Test
   public void cancelWithException() {
     CompletableFuture<?> future = new CompletableFuture<>();
     future.completeExceptionally(new CancellationException());
+
+    assertEquals(CancellationException.class, Util.exceptionFromCallback(future).getClass());
     Util.assertException(future, List.of(CancellationException.class));
   }
 
@@ -39,6 +44,9 @@ public void cancelParent() {
     assertFalse(future2.isCancelled()); // This was NOT explicitly cancelled!
     assertTrue(future2.isCompletedExceptionally());
 
+    assertEquals(CancellationException.class, Util.exceptionFromCallback(future).getClass());
+    assertEquals(CompletionException.class, Util.exceptionFromCallback(future2).getClass());
+
     Util.assertException(future, List.of(CancellationException.class));
     Util.assertException(future2, List.of(CompletionException.class, CancellationException.class));
   }
@@ -57,7 +65,9 @@ public void cancelChild() {
     assertTrue(future2.isCancelled());
     assertTrue(future2.isCompletedExceptionally());
 
+    assertEquals(CancellationException.class, Util.exceptionFromCallback(future2).getClass());
     Util.assertException(future2, List.of(CancellationException.class));
 
   }
+
 }

Diff for: src/test/java/se/krka/futures/CancelTest.java

@@ -7,6 +7,9 @@
 import java.util.concurrent.CancellationException;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
+import java.util.concurrent.TimeoutException;
+
+import static org.junit.Assert.assertEquals;
 
 public class ExceptionTest {
 
@@ -15,9 +18,35 @@ public class ExceptionTest {
           IllegalArgumentException.class
   );
 
+  @Test
+  public void testExceptionSimple() {
+    CompletableFuture<Object> future = new CompletableFuture<>();
+    future.completeExceptionally(new IllegalArgumentException());
+    assertEquals(IllegalArgumentException.class, Util.exceptionFromCallback(future).getClass());
+    Util.assertException(future, List.of(CompletionException.class, IllegalArgumentException.class));
+
+    // Wrapped, since it has gotten a transform operation!
+    CompletableFuture<Object> future2 = future.thenApply(x -> x);
+    assertEquals(CompletionException.class, Util.exceptionFromCallback(future2).getClass());
+    Util.assertException(future2, List.of(CompletionException.class, IllegalArgumentException.class));
+
+    // Same for rethrowing the exception in a transform
+    CompletableFuture<Object> future3 = future.exceptionally(e -> Util.doThrow((RuntimeException) e));
+    assertEquals(CompletionException.class, Util.exceptionFromCallback(future3).getClass());
+    Util.assertException(future3, List.of(CompletionException.class, IllegalArgumentException.class));
+
+    // Same for doing a copy of the future
+    CompletableFuture<Object> future4 = future.copy();
+    assertEquals(CompletionException.class, Util.exceptionFromCallback(future4).getClass());
+    Util.assertException(future4, List.of(CompletionException.class, IllegalArgumentException.class));
+
+  }
+
   @Test
   public void testExceptionTypeSupply() {
-    Util.assertException(CompletableFuture.supplyAsync(() -> Util.doThrow(new IllegalArgumentException())), EXPECTED);
+    CompletableFuture<Object> future = CompletableFuture.supplyAsync(() -> Util.doThrow(new IllegalArgumentException()));
+    Util.assertException(future, EXPECTED);
+    assertEquals(CompletionException.class, Util.exceptionFromCallback(future).getClass());
   }
 
   @Test
@@ -60,7 +89,24 @@ public void testExceptionTypeComposeThrowWrapped() {
   public void testCancelException() {
     CompletableFuture<Object> future = new CompletableFuture<>();
     future.cancel(true);
+    assertEquals(CancellationException.class, Util.exceptionFromCallback(future).getClass());
     Util.assertException(future, List.of(CancellationException.class));
   }
 
+  @Test
+  public void testCancelException2() {
+    CompletableFuture<Object> future = new CompletableFuture<>();
+    future.completeExceptionally(new CancellationException());
+    assertEquals(CancellationException.class, Util.exceptionFromCallback(future).getClass());
+    Util.assertException(future, List.of(CancellationException.class));
+  }
+
+  @Test
+  public void testTimeoutException() {
+    CompletableFuture<Object> future = new CompletableFuture<>();
+    future.completeExceptionally(new TimeoutException());
+    assertEquals(TimeoutException.class, Util.exceptionFromCallback(future).getClass());
+    Util.assertException(future, List.of(CompletionException.class, TimeoutException.class));
+  }
+
 }