Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 36 ยท Reactive and Messaging

The Event Loop, Blocking Code and Virtual Threads

Understand the Vert.x event loop under Quarkus, which endpoints run on I/O or worker threads, how @Blocking and @RunOnVirtualThread work and how to avoid stalls.

Under every Quarkus HTTP endpoint sits Eclipse Vert.x and Netty. Vert.x accepts connections with a handful of event-loop threads (by default twice the number of CPU cores). Each of those threads handles thousands of connections by never waiting: it reads a request, starts some work, and moves on to the next event. That is why a tiny Quarkus service can serve a lot of traffic in a few megabytes of memory.

The price is one rule that every Quarkus developer must know: never block an event-loop thread. If one blocks for a second, every connection assigned to that thread freezes for a second. This lesson explains which of your methods run where, how to hand blocking work to a different thread, and when virtual threads are the easier answer. It follows Mutiny.

The real Quarkus runtime is not available here, so the TryIts model the two thread types with plain Java executors.

Two kinds of threads

Thread Name in logs Good for Bad for
Event loop (I/O) vert.x-eventloop-thread-0 Parsing requests, calling reactive clients, small CPU work JDBC, file I/O, Thread.sleep, Future.get(), heavy CPU
Worker executor-thread-1 Blocking calls, JDBC, legacy libraries Nothing; it is a normal pool, but it is limited in size
Virtual thread quarkus-virtual-thread-0 Blocking code written simply Code that pins carrier threads (rare, mostly old synchronized blocks)

Where does my endpoint run?

With Quarkus REST (the default server-side REST stack in recent Quarkus versions, formerly called RESTEasy Reactive) the decision is made from your method's return type:

Java
@Path("/books")
public class BookResource {

    @GET @Path("/plain")
    public List<Book> plain() { ... }           // worker thread: blocking is fine

    @GET @Path("/reactive")
    public Uni<List<Book>> reactive() { ... }   // event loop: must NOT block

    @GET @Path("/stream")
    public Multi<Book> stream() { ... }         // event loop
}
  • A method that returns a plain object (List<Book>, Book, Response, void) is assumed to be blocking and runs on a worker thread.
  • A method that returns Uni, Multi or CompletionStage is assumed to be reactive and runs on the event loop.

You can override both guesses:

Java
@GET @Path("/legacy")
@Blocking                              // returns a Uni but must be run on a worker
public Uni<String> legacy() { ... }

@GET @Path("/fast")
@NonBlocking                           // returns a plain value but is quick and non-blocking
public String fast() { return "pong"; }

@NonBlocking on a plain method is a small optimization for trivial endpoints such as health pings: it avoids the thread hop. Use it only when you are sure the code never waits.

Choose the thread by return type

Plain value Worker thread. Blocking is OK.
Uni or Multi Event loop. Never block.
@RunOnVirtualThread A virtual thread. Blocking is OK.

Annotations override the default when you know better.

1 / 2

What a stall looks like

Imagine one event-loop thread serving a health check every 100 ms. Now one handler blocks for 600 ms. All checks queued behind it are late:

Java Stand-in: one blocked event loop freezes everything

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In the first half, ping 2 (scheduled for 200 ms) waits until the blocking handler is done. In the second half, pings keep being answered on time, because only the worker sleeps.

Calling blocking code from reactive code

Sometimes you are inside a Uni pipeline and must call a blocking library. Move that step to a worker:

Java
import io.smallrye.mutiny.infrastructure.Infrastructure;

public Uni<String> loadReport(long id) {
    return Uni.createFrom().item(() -> legacyClient.fetchReport(id))   // blocking call
              .runSubscriptionOn(Infrastructure.getDefaultWorkerPool());
}

runSubscriptionOn makes the subscription, and so the supplier, run on the worker pool, and the result flows back into the pipeline. The mirror image is emitOn, which moves the downstream steps to another executor.

In Hibernate Reactive code the rule is similar: do not call blocking Panache methods on the event loop. Quarkus detects most of these mistakes and throws IllegalStateException: You have attempted to perform a blocking operation on a IO thread. If you see that message, the fix is almost always @Blocking, a worker hop, or switching to a reactive client. Reactive data access is covered in Data with Panache in chapter 4.

Virtual threads

Java 21 added virtual threads: cheap threads that the JVM schedules itself, so blocking code costs almost nothing while it waits. Quarkus lets you opt in per method:

Java
import io.smallrye.common.annotation.RunOnVirtualThread;

@GET @Path("/{id}")
@RunOnVirtualThread
public Book find(@PathParam("id") long id) {
    return repository.findById(id);     // blocking JDBC is fine here
}

This gives you the simple, readable imperative style with concurrency close to reactive code. Trade-offs: pinning (a virtual thread inside a synchronized block or a native call holds its carrier thread), no reactive back pressure, and for streaming use cases Multi is still the better model. Many teams choose virtual threads for ordinary CRUD services and Mutiny where they stream or fan out many calls.

Java Stand-in: 10,000 blocking tasks on virtual threads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Choosing a style

  • Reactive (Uni/Multi): streaming, fan-out of many remote calls, strict memory budgets, reactive messaging.
  • Virtual threads: normal request-response services with JDBC or blocking SDKs.
  • Plain worker threads: the default; fine for most services and the easiest to debug.

Do not mix them accidentally. A reactive endpoint that calls JDBC is a stalling bug waiting for load.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a Quarkus REST method that returns Uni<Book> run by default?

    Reactive return types are assumed to be non-blocking and are run on the event loop, so they must not block.
  2. 2. What is the effect of blocking an event-loop thread for one second?

    One loop thread serves many connections, and while it is blocked none of them make progress.
  3. 3. Which annotation runs a plain-looking method on a virtual thread?

    @RunOnVirtualThread (from SmallRye Common) tells Quarkus to execute the method on a virtual thread.
  4. 4. How do you call a blocking library from inside a Mutiny pipeline?

    runSubscriptionOn(Infrastructure.getDefaultWorkerPool()) moves the blocking supplier off the event loop.

Summary

  • Event-loop threads are few and must never block; worker threads may block.
  • Return type decides the default thread: plain types go to workers, Uni/Multi to the loop; @Blocking/@NonBlocking override it.
  • Use runSubscriptionOn to call blocking code from reactive code.
  • @RunOnVirtualThread gives blocking-style code cheap concurrency.

Next: Reactive Messaging with Kafka and AMQP