Adding the ability to supply an IO with externally managed futures

jnape · jnape · commit 7bc9def4dde6 · 2019-01-27T18:07:48.000-06:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - `MapLens#asCopy` has overload taking copy function
 - `MapLens#valueAt` has overload taking copy function
 - `SortWith` for sorting an `Iterable` given a `Comparator` over its elements
+- `IO#externallyManaged`, for supplying an `IO` with externally-managed futures
 
 ### Fixed
 - issue where certain ways to compose `Effect`s unintentionally nullified the effect 
diff --git a/src/main/java/com/jnape/palatable/lambda/io/IO.java b/src/main/java/com/jnape/palatable/lambda/io/IO.java
@@ -5,9 +5,14 @@
 import com.jnape.palatable.lambda.functor.Applicative;
 import com.jnape.palatable.lambda.monad.Monad;
 
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executor;
 import java.util.function.Function;
+import java.util.function.Supplier;
 
 import static com.jnape.palatable.lambda.adt.Unit.UNIT;
+import static com.jnape.palatable.lambda.functions.specialized.checked.CheckedSupplier.checked;
+import static java.util.concurrent.CompletableFuture.supplyAsync;
 
 /**
  * A {@link Monad} representing some effectful computation to be performed.
@@ -17,12 +22,38 @@
 public interface IO<A> extends Monad<A, IO<?>> {
 
     /**
-     * Run the effect represented by this {@link IO} instance
+     * Run the effect represented by this {@link IO} instance, blocking the current thread until the effect terminates.
      *
      * @return the result of the effect
      */
     A unsafePerformIO();
 
+    /**
+     * Returns a {@link CompletableFuture} representing the result of this eventual effect. By default, this will
+     * immediately run the effect in terms of the implicit {@link Executor} available to {@link CompletableFuture}
+     * (usually the {@link java.util.concurrent.ForkJoinPool}). Note that specific {@link IO} constructions may allow
+     * this method to delegate to externally-managed {@link CompletableFuture} instead of synthesizing their own.
+     *
+     * @return the {@link CompletableFuture} representing this {@link IO}'s eventual result
+     * @see IO#unsafePerformAsyncIO(Executor)
+     */
+    default CompletableFuture<A> unsafePerformAsyncIO() {
+        return supplyAsync(this::unsafePerformIO);
+    }
+
+    /**
+     * Returns a {@link CompletableFuture} representing the result of this eventual effect. By default, this will
+     * immediately run the effect in terms of the provided {@link Executor}. Note that specific {@link IO}
+     * constructions may allow this method to delegate to externally-managed {@link CompletableFuture} instead of
+     * synthesizing their own.
+     *
+     * @return the {@link CompletableFuture} representing this {@link IO}'s eventual result
+     * @see IO#unsafePerformAsyncIO()
+     */
+    default CompletableFuture<A> unsafePerformAsyncIO(Executor executor) {
+        return supplyAsync(this::unsafePerformIO, executor);
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -116,4 +147,35 @@ static IO<Unit> io(Runnable runnable) {
     static <A> IO<A> io(Fn1<Unit, A> fn1) {
         return io(() -> fn1.apply(UNIT));
     }
+
+    /**
+     * Static factory method for creating an {@link IO} from an externally managed source of
+     * {@link CompletableFuture completable futures}.
+     * <p>
+     * Note that constructing an {@link IO} this way results in no intermediate futures being constructed by either
+     * {@link IO#unsafePerformAsyncIO()} or {@link IO#unsafePerformAsyncIO(Executor)}, and {@link IO#unsafePerformIO()}
+     * is synonymous with invoking {@link CompletableFuture#get()} on the externally managed future.
+     *
+     * @param supplier the source of externally managed {@link CompletableFuture completable futures}
+     * @param <A>      the result type
+     * @return the {@link IO}
+     */
+    static <A> IO<A> externallyManaged(Supplier<CompletableFuture<A>> supplier) {
+        return new IO<A>() {
+            @Override
+            public A unsafePerformIO() {
+                return checked(() -> unsafePerformAsyncIO().get()).get();
+            }
+
+            @Override
+            public CompletableFuture<A> unsafePerformAsyncIO() {
+                return supplier.get();
+            }
+
+            @Override
+            public CompletableFuture<A> unsafePerformAsyncIO(Executor executor) {
+                return supplier.get();
+            }
+        };
+    }
 }
diff --git a/src/test/java/com/jnape/palatable/lambda/io/IOTest.java b/src/test/java/com/jnape/palatable/lambda/io/IOTest.java
@@ -9,9 +9,15 @@
 import testsupport.traits.FunctorLaws;
 import testsupport.traits.MonadLaws;
 
+import java.util.concurrent.CompletableFuture;
+
 import static com.jnape.palatable.lambda.adt.Unit.UNIT;
 import static com.jnape.palatable.lambda.functions.Fn0.fn0;
+import static com.jnape.palatable.lambda.io.IO.externallyManaged;
 import static com.jnape.palatable.lambda.io.IO.io;
+import static java.util.concurrent.CompletableFuture.completedFuture;
+import static java.util.concurrent.Executors.newFixedThreadPool;
+import static java.util.concurrent.ForkJoinPool.commonPool;
 import static org.junit.Assert.assertEquals;
 
 @RunWith(Traits.class)
@@ -29,4 +35,23 @@ public void staticFactoryMethods() {
         assertEquals((Integer) 1, io(fn0(() -> 1)).unsafePerformIO());
         assertEquals(UNIT, io(() -> {}).unsafePerformIO());
     }
+
+    @Test(timeout = 100)
+    public void unsafePerformAsyncIOWithoutExecutor() {
+        assertEquals((Integer) 1, io(() -> 1).unsafePerformAsyncIO().join());
+    }
+
+    @Test(timeout = 100)
+    public void unsafePerformAsyncIOWithExecutor() {
+        assertEquals((Integer) 1, io(() -> 1).unsafePerformAsyncIO(newFixedThreadPool(1)).join());
+    }
+
+    @Test
+    public void delegatesToExternallyManagedFuture() {
+        CompletableFuture<Integer> future = completedFuture(1);
+        IO<Integer> io = externallyManaged(() -> future);
+        assertEquals((Integer) 1, io.unsafePerformIO());
+        assertEquals((Integer) 1, io.unsafePerformAsyncIO().join());
+        assertEquals((Integer) 1, io.unsafePerformAsyncIO(commonPool()).join());
+    }
 }
