BackendBench
Coffee

Unravel › Java concepts › Jakarta and other frameworks

Concurrency

Vert.x verticles and the event loop

Vert.x is a toolkit for non-blocking applications on the JVM.

🔎 Unravel this examplePrerequisites (1)

Learn these first

Lambdas and functional interfaces

At a glance

Mental model

A restaurant with a few very fast waiters who never wait at the kitchen.

What happens, in order
  1. 1A verticle extends AbstractVerticle and starts in start(Promise<Void> startPromise)vertx.deployVerticle(new MainVerticle()) deploys it; instances can be multiplied to use all CPU cores.
  2. 2A Router maps routes to handlers: router.get("/orders/:id").handler(ctx -> ctx.response().end(...))createHttpServer().requestHandler(router).listen(8080) starts the server.
  3. 3Results are returned as Future<T>; compose them with compose, map, onSuccess, onFailure rather than blockingPromise<T> is the writable side.
  4. 4The EventBus delivers messages between verticles by address, inside one JVM or across a cluster: eventBus.request("price.lookup", sku)
Remember
Watch out
Blocking calls on the event loopForgetting failure handlers on futuresSharing mutable state between verticlesA single verticle instance on a many-core machine
Example (highlighted lines explain it)
public class MainVerticle extends AbstractVerticle {    @Override    public void start(Promise<Void> startPromise) {        Router router = Router.router(vertx);        router.get("/health").handler(ctx -> ctx.response().end("ok"));        vertx.createHttpServer()            .requestHandler(router)            .listen(8080)            .onSuccess(server -> startPromise.complete())            .onFailure(startPromise::fail);    }}
  1. line 1 uses Verticle, the core of Vert.x verticles and the event loop
  2. line 3 uses Promise, the core of Vert.x verticles and the event loop
  3. line 4 uses Router, the core of Vert.x verticles and the event loop
  4. line 6 uses createHttpServer, the core of Vert.x verticles and the event loop
  5. line 9 uses Promise, the core of Vert.x verticles and the event loop
  6. line 10 uses Promise, the core of Vert.x verticles and the event loop
Read the full explanation (about 2 min)

Vert.x is a toolkit for non-blocking applications on the JVM. Code runs in small units called verticles, each tied to one event-loop thread, and communicates through callbacks, futures and an event bus.

A mental model

A restaurant with a few very fast waiters who never wait at the kitchen. They take an order, hand it off, and immediately serve the next table; when a dish is ready the kitchen rings a bell and the waiter picks it up.

How it works

A verticle extends AbstractVerticle and starts in start(Promise<Void> startPromise). vertx.deployVerticle(new MainVerticle()) deploys it; instances can be multiplied to use all CPU cores.

A Router maps routes to handlers: router.get("/orders/:id").handler(ctx -> ctx.response().end(...)). createHttpServer().requestHandler(router).listen(8080) starts the server.

Results are returned as Future<T>; compose them with compose, map, onSuccess, onFailure rather than blocking. Promise<T> is the writable side.

The EventBus delivers messages between verticles by address, inside one JVM or across a cluster: eventBus.request("price.lookup", sku).

Going deeper

The golden rule: never block an event-loop thread. Database drivers with blocking APIs, Thread.sleep and heavy computation freeze every request on that loop; offload with executeBlocking or worker verticles. Vert.x logs "Thread blocked" warnings after 2 seconds.

State inside a verticle is touched by one thread only, so it needs no locks, but sharing mutable objects between verticles reintroduces data races.

Failure handling is explicit. An exception thrown in a callback is not caught by an outer try/catch; attach onFailure handlers or a route failure handler.

Under the hood

Each verticle is bound to a Context that is associated with one event-loop thread (a Netty EventLoop). Callbacks are always executed on that thread, giving the "multi-reactor" model: N loops (default 2 times the core count), each handling thousands of connections through non-blocking I/O.

Common mistakes

  • Blocking calls on the event loop.
  • Forgetting failure handlers on futures.
  • Sharing mutable state between verticles.
  • A single verticle instance on a many-core machine.

How Unravel recognises it

When you paste code, Unravel looks for these signs of vert.x verticles and the event loop. Spotting them yourself is a good habit when you read unfamiliar code:

Part of a learning path

Related concepts

Reactive programming (Reactor Mono and Flux)SpringExecutors and thread poolsConcurrency

Frequently asked questions

What is Vert.x verticles and the event loop?

Vert.x is a toolkit for non-blocking applications on the JVM. Code runs in small units called verticles, each tied to one event-loop thread, and communicates through callbacks, futures and an event bus.

What are the most common mistakes with Vert.x verticles and the event loop?

Blocking calls on the event loop. Forgetting failure handlers on futures. Sharing mutable state between verticles. A single verticle instance on a many-core machine.

How can I see Vert.x verticles and the event loop in real code?

Paste your own Java into Unravel and it will point out where vert.x verticles and the event loop appears, explain how it works at the detail level you choose, and draw the flow of the code around it.