Java 8: Writing asynchronous code with CompletableFuture
Java 8 introduced a lot of cool features, whereas lambdas and streams caught much of the attention.
What you may have missed is the
You probably already know about Futures
A Future represents the pending result of an asynchronous computation. It offers a method —
get — that returns the result of the computation when it's done.
The problem is that a call to
get is blocking until the computation is done. This is quite restrictive and can quickly make the asynchronous computation pointless.
Sure — you can keep coding all scenarios into the job you're sending to the executor, but why should you have to worry about all the plumbing around the logic you really care about?
This is where
CompletableFuture saves the day
Beside implementing the
CompletableFuture also implements the
CompletionStage is a promise. It promises that the computation eventually will be done.
The great thing about the
CompletionStage is that it offers a vast selection of methods that let you attach callbacks that will be executed on completion.
This way we can build systems in a non-blocking fashion.
Ok, enough chatting, let's start coding!
The simplest asynchronous computation
Let's start with the absolute basics — creating a simple asynchronous computation.
It's as easy as that.
supplyAsync takes a
Supplier containing the code we want to execute asynchronously — in our case the
If you've worked a bit with Futures in the past, you may wonder where the
Executor went. If you want to, you can still define it as a second argument. However, if you leave it out it will be submitted to the
Attaching a callback
Our first asynchronous task is done. Let's add a callback to it!
The beauty of a callback is that we can say what should happen when an asynchronous computation is done without waiting around for the result.
In the first example, we simply sent a message asynchronously by executing
sendMsg in its own thread.
Now let's add a callback where we notify about how the sending of the message went.
thenAccept is one of many ways to add a callback. It takes a
Consumer — in our case
notify — which handles the result of the preceding computation when it's done.
Chaining multiple callbacks
If you want to continue passing values from one callback to another,
thenAccept won't cut it since
Consumer doesn't return anything.
To keep passing values, you can simply use
thenApply takes a
Function which accepts a value, but also return one.
To see how this works, let's extend our previous example by first finding a receiver.
CompletableFuture.supplyAsync(this::findReceiver) .thenApply(this::sendMsg) .thenAccept(this::notify);
Now the asynchronous task will first find a receiver, then send a message to the receiver before it passes the result on to the last callback to notify.
Building asynchronous systems
When building bigger asynchronous systems, things work a bit differently.
You'll usually want to compose new pieces of code based on smaller pieces of code. Each of these pieces would typically be asynchronous — in our case returning
sendMsg has been a normal blocking function. Let's now assume that we got a
sendMsgAsync method that returns a
If we kept using
thenApply to compose the example above, we would end up with nested
CompletableFuture.supplyAsync(this::findReceiver) .thenApply(this::sendMsgAsync); // Returns type CompletionStage<CompletionStage<String>>
We don't want that, so instead we can use
thenCompose which allows us to give a
Function that returns a
CompletionStage. This will have a flattening effect like a flatMap.
CompletableFuture.supplyAsync(this::findReceiver) .thenCompose(this::sendMsgAsync); // Returns type CompletionStage<String>
This way we can keep composing new functions without losing the one layered
Callback as a separate task using the async suffix
Until now all our callbacks have been executed on the same thread as their predecessor.
If you want to, you can submit the callback to the
ForkJoinPool.commonPool() independently instead of using the same thread as the predecessor. This is done by using the async suffix version of the methods
Let's say we want to send two messages at one go to the same receiver.
CompletableFuture<String> receiver = CompletableFuture.supplyAsync(this::findReceiver); receiver.thenApply(this::sendMsg); receiver.thenApply(this::sendOtherMsg);
In the example above, everything will be executed on the same thread. This results in the last message waiting for the first message to complete.
Now consider this code instead.
CompletableFuture<String> receiver = CompletableFuture.supplyAsync(this::findReceiver); receiver.thenApplyAsync(this::sendMsg); receiver.thenApplyAsync(this::sendMsg);
By using the async suffix, each message is submitted as separate tasks to the
ForkJoinPool.commonPool(). This results in both the
sendMsg callbacks being executed when the preceding calculation is done.
The key is — the asynchronous version can be convenient when you have several callbacks dependent on the same computation.
What to do when it all goes wrong
As you know, bad things can happen. And if you've worked with
Future before, you know how bad it could get.
CompletableFuture has a nice way of handling this, using
CompletableFuture.supplyAsync(this::failingMsg) .exceptionally(ex -> new Result(Status.FAILED)) .thenAccept(this::notify);
exceptionally gives us a chance to recover by taking an alternative function that will be executed if preceding calculation fails with an exception.
This way succeeding callbacks can continue with the alternative result as input.
If you need more flexibility, check out
handle for more ways of handling errors.
Handling timeouts in a controlled way
Timeouts are something that us coders often need to take care of. Sometimes we simply can't hang around waiting for a computation to be done.
This also applies to CompletableFutures. We need a way to say to our CompletableFutures how long we're willing to wait and what to do if the time runs out.
This has been addressed in Java 9 by introducing two new methods that'll enable us to take care of timeouts —
So say we got a hanging message, and we don't want to wait forever for it to finish.
orTimeout does is to complete our CompletableFuture exceptionally if it doesn't complete within the timeout we specify.
CompletableFuture.supplyAsync(this::hangingMsg) .orTimeout(1, TimeUnit.MINUTES);
There we go! If our hanging message doesn't complete in one minute, a
TimeoutException will be thrown.
This exception can then be handled by the
exceptionally callback we looked at earlier.
Another option is to use the
completeOnTimeout which gives us the possibility to provide an alternative value.
To me this is way better than just throwing exceptions around, because it allows us to recover in a nice controlled manner.
CompletableFuture.supplyAsync(this::hangingMsg) .completeOnTimeout(new Result(Status.TIMED_OUT),1, TimeUnit.MINUTES);
Now, if our hanging message doesn't return in time, we'll return a result with the status
Callback depending on multiple computations
Sometimes it would be really helpful to be able to create a callback that is dependent on the result of two computations. This is where
thenCombine becomes handy.
thenCombine allows us to register a
BiFunction callback depending on the result of two
To see how this is done, let’s in addition to finding a receiver also execute the heavy job of creating some content before sending a message.
CompletableFuture<String> to = CompletableFuture.supplyAsync(this::findReceiver); CompletableFuture<String> text = CompletableFuture.supplyAsync(this::createContent); to.thenCombine(text, this::sendMsg);
First, we've started two asynchronous jobs — finding a receiver and creating some content. Then we use
thenCombine to say what we want to do with the result of these two computations by defining our
It's worth mentioning that there is another variant of
thenCombine as well — called
runAfterBoth. This version takes a
Runnable not caring about the actual values of the preceding computation — only that they're actually done.
Callback dependent on one or the other
Ok, so we've now covered the scenario where you depend on two computations. Now, what about when you just need the result of one of them?
Let’s say you have two sources of finding a receiver. You’ll ask both, but will be happy with the first one returning with a result.
CompletableFuture<String> firstSource = CompletableFuture.supplyAsync(this::findByFirstSource); CompletableFuture<String> secondSource = CompletableFuture.supplyAsync(this::findBySecondSource); firstSource.acceptEither(secondSource, this::sendMsg);
As you can see, it's solved easily by
acceptEither taking the two awaiting calculations and a
Consumer that will be executed with the result of the first one to return.
That covers the basics of what
CompletableFuture has to offer. There are still a few more methods to check out, so make sure to check out the documentation for more details.