Add a description to CompletableFuture orTimeout

What is the easy way to add some addition info into the timeout exception? Suppose I have a code like that:

CompletableFuture<ResutType> getSomething()
{
  ... return someFuture.orTimeout(15, SECONDS);
}

This is all I'm getting currently downstream later on when callers of the method trying to do get():

java.util.concurrent.ExecutionException: java.util.concurrent.TimeoutException
    at java.base/java.util.concurrent.CompletableFuture.reportGet(CompletableFuture.java:396)
	at java.base/java.util.concurrent.CompletableFuture.get(CompletableFuture.java:2073)

I need to add more info - which operation has timed out, how long timeout was, etc.. In other words I need some message to the exception like "The Something timed-out in 15s", ideally use a supplier like:

CompletableFuture<ResutType> getSomething()
{
   return someFuture.orTimeout(15, SECONDS, () -> new TimeoutException("The Something timed-out in 15s"));
}

You can use the same facility as the CompletableFuture’s internal timeout handling:

public static <T> CompletableFuture<T> customTimeOut(
    CompletableFuture<T> cf, long time, TimeUnit unit,
    Supplier<? extends Exception> s) {

    CompletableFuture.delayedExecutor(time, unit, cf.defaultExecutor())
        .execute(() -> { if(!cf.isDone()) cf.completeExceptionally(s.get()); });

  return cf;
}

Note that the isDone() check is not strictly necessary, as completeExceptionally does nothing if the future is already completed. The check is only there to prevent the potential expensive exception construction when not necessary. It’s still possible, but rather unlikely that the future gets completed right between the isDone() and the completeExceptionally call, but nothing bad will happen then, as said, because completeExceptionally does the right thing anyway.

You can test it like

public static void main(String[] args) {
    for(int timeOut = 1; timeOut < 5; timeOut += 2) {
        System.out.println("time-out " + timeOut + " sec");
  
        CompletableFuture<String> cf = customTimeOut(
            CompletableFuture.supplyAsync(() -> {
                LockSupport.parkNanos(2_000_000_000);
                return "result";
            }),
            timeOut, TimeUnit.SECONDS,
            () -> new TimeoutException("timeout with my custom message")
        );
    
        try {
            System.out.println("ordinary result: " + cf.join());
        }
        catch(Exception ex) {
            ex.printStackTrace(System.out);
        }
    }
}

time-out 1 sec
java.util.concurrent.CompletionException: java.util.concurrent.TimeoutException: timeout with my custom message
	at java.base/java.util.concurrent.CompletableFuture.reportJoin(CompletableFuture.java:413)
	at java.base/java.util.concurrent.CompletableFuture.join(CompletableFuture.java:2118)
	at CF.main(CF.java:32)
Caused by: java.util.concurrent.TimeoutException: timeout with my custom message
	at CF.lambda$2(CF.java:28)
	at CF.lambda$0(CF.java:13)
	at java.base/java.util.concurrent.ForkJoinTask$RunnableExecuteAction.exec(ForkJoinTask.java:1395)
	at java.base/java.util.concurrent.ForkJoinTask.doExec(ForkJoinTask.java:373)
	at java.base/java.util.concurrent.ForkJoinPool$WorkQueue.topLevelExec(ForkJoinPool.java:1182)
	at java.base/java.util.concurrent.ForkJoinPool.scan(ForkJoinPool.java:1655)
	at java.base/java.util.concurrent.ForkJoinPool.runWorker(ForkJoinPool.java:1622)
	at java.base/java.util.concurrent.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:165)
time-out 3 sec
ordinary result: result

[Try it online!](https://tio.run/##hVPBbtswDL37K7icbDQxsgK7zGmHoe1OW3tIexqGQVWYVIksGRLVxijy7RkVO07TJB0ByxD1SD49UnPxLAbzyWK9VmVlHcGcHXkgpXNpjQzOoaH8ypaVRhKPGn8ECg6L5CP4vSrxwSj6P8oGullKrEhZ8zFaW7nw@U9ex6GKsCPwaTAyZsojRCt0RZJU4VErCVIL7@GXUCZ5TYCt9XsSxL/R/SUcXDI6ZfBky0j1LlC6iYx2HDvtg7ZmBsTwPmxVgMBLH7acRt8Al4Rm4qG7@iX4DCKv0wXyCWpR4@RmiTKQdWlTpMktp3w8FUFTd5xlXa5oOW4OME0zGFzCK6hp@onDlL@2Bhkdc8imKHa8hNZ16vMZEiMKWGXFjqNDpmU4rNg4VskRWZ@tmkDJoqdjcsrMfv8B4WbtXRubMldlaKMZSwwX8LnoNiP4stucXcD528ho49oTljmPUV5xAdIm7UX8gD3Qg7NdMO88yl5WtPF7aQ7b2fCNPWVGJ4bgdK987HX93ddGbgU/iIr2ZpzzSrjFrTDWp@d/h8Ph9usI71urfs@h5673DkGrrH/ga8XYjWY@vrm6u70eH0Ib1gZf4P0zbQSO@r4oeoKybuWBEr0XM@ztD94b/nt@cvURUY7107qJMoLhzV2/bvrK0zq3PFfZO31WezspSD6lHXV@eNmRorhsio1JyMW9ExLTHY@T@Vft2K@S9fof "Java (JDK) – Try It Online")

You can use exceptionallyCompose (or any of the async variants of this method) for that:

public final class Example {
    public static void main(String[] args) throws ExecutionException, InterruptedException {
        CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
                    sleep(3000);
                    return "DONE";
                })
                .orTimeout(1000, TimeUnit.MILLISECONDS)
                .exceptionallyCompose(throwable -> {
                    if (throwable instanceof TimeoutException) {
                        var tex = new TimeoutException("The Something timed-out in 15s");
                        return CompletableFuture.failedFuture(tex);
                    }
                    return CompletableFuture.failedFuture(throwable);
                });

        sleep(2000);
        future.get();
        sleep(5000);
    }

    private static void sleep(long ms) {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        }
    }
}

If your code fails due to a TimeoutException, you can return a TimeoutException (or any other throwable) that has more detail via a failed CompletableFuture. Otherwise, you can just return the same throwable that caused one of the previous stages to be completed exceptionally.

For example, if there had been some RuntimeException in supplyAsync, future.get() would still cause a RuntimeException (wrapped within an ExecutionException) to be thrown. If there is no exception (i.e. also no timeout), you get() your result normally.

With that knowledge you can write your own little orTimeout wrapper, for example:

public static <T> CompletableFuture<T> orTimeout(
        CompletableFuture<T> cf,
        long timeout, TimeUnit unit
) {
    return cf.orTimeout(timeout, unit).exceptionallyCompose(throwable -> {
        if (throwable instanceof TimeoutException) {
            final var msg = String.format(
                    "The Something timed-out in %d %s.",
                    timeout, unit
            );
            return CompletableFuture.failedFuture(new TimeoutException(msg));
        }
        return CompletableFuture.failedFuture(throwable);
    });
}

and then use it for all CompletableFutures like so:

CompletableFuture<String> future = orTimeout(CompletableFuture.supplyAsync(() -> {
    sleep(10000);
    return "DONE";
}), 1000, TimeUnit.MILLISECONDS);

Since you are expecting a timeout, consider making it part of the return type instead of dealing with the TimeoutException. One way is to change the result type to Either<Timeout, Result> using the Either type of the Vavr library.

var future = CompletableFuture.<Either<Timeout, Result>>supplyAsync(() ->
    Either.right(lengthyCalculation()))
.completeOnTimeout(
    Either.left(new Timeout("Lengthy Calculation timed out", 12)), 1, SECONDS);

Once the future completed and you got hold of its value, use one of the many methods of Either to proceed. In the simplest case

Result result = future.get()
    .getOrElseThrow(timeout -> new RuntimeException(...));

Naively I would say.

CompletableFuture future = CompletableFuture.runAsync( () ->{
    try{
        someFuture.get(15, TimeUnit.MILLISECONDS);
    } catch(Exception e){
        throw new RuntimeException("detailed message", e);
    }
});

Of course you should be a bit more specific about the exceptions, but I think this is the gist of the issue.