Vertx: executeBlocking() vs Future. What's the difference?

Question

Vertx docs suggests to use executeBlocking() method when one needs to call blocking API. On the other hand Vertx also offers a notion of Future which basically do the same thing. But the executeBlocking() method isn't static. It is also not a simple wrapper around Future, and if you look at its implementation you'll see that it's pretty complex. What's the difference between these two?

Assume that I want to execute some long running task in an async way. Is there any difference between these two methods?

method 1:

doTheJob() {
    Future<Void> future = Future.future();
    executeLongRunningBlockingOperation();
    future.complete();
    return future;
}

doTheJob().setHandler(asyncResult -> {
    // ... handle result
});

method 2:

vertx.executeBlocking(future -> {
    executeLongRunningBlockingOperation();
    future.complete();
}, res -> {
    // ... handle result
});

Answer 1

Your first example is not a correct usage of Future. The call to executeLongRunningBlockingOperation() will block the main thread until that method has completed — i.e. nothing else can happen until the blocking operation finishes. In your second example the blocking call is spun off into a background thread and other things continue to happen while it executes.

To illustrate this with a more complete example, this code:

public void executeLongRunningBlockingOperation() {
    Thread.sleep(5000);
}

public Future<Void> doTheJob() { 
    System.out.println("Doing the job...");
    Future<Void> future = Future.future();
    executeLongRunningBlockingOperation();
    // this line will not be called until executeLongRunningBlockingOperation returns!
    future.complete();
    // nor will this method! This means that the method won't return until the long operation is done!
    return future;
}

public static void main(String[] args) {
    doTheJob().setHandler(asyncResult -> {
        System.out.println("Finished the job");
    });
    System.out.println("Doing other stuff in the mean time...");
}

Will produce the following output:

Doing the job...
Finished the job
Doing other stuff in the mean time...

Whereas this code (using the executeBlocking):

...
public Future<Void> doTheJob() { 
    System.out.println("Doing the job...");
    Future<Void> future = Future.future();
    Vertx vertx = Vertx.vertx();
    vertx.executeBlocking(call -> {
        executeLongRunningBlockingOperation();
        call.complete;
    }, result -> {
        // this will only be called once the blocking operation is done
        future.complete();
    });
    // this method returns immediately since we are not blocking the main thread
    return future;
}
...

Will produce:

Doing the job...
Doing other stuff in the mean time...
Finished the job

If you'd like to develop a better understanding of Vert.x I'd recommend the following hands-on tutorials:

https://vertx.io/docs/guide-for-java-devs/

http://escoffier.me/vertx-hol/