Choosing Quarkus Reactive Execution: Mutiny for Non-Blocking I/O Endpoints

The Problem: Thread Starvation Under Concurrent I/O

When a Quarkus service handles thousands of simultaneous requests that each wait on a database query or an external HTTP call, the default blocking model assigns one worker thread per request. Those threads sit idle while the I/O completes, and the worker pool eventually exhausts itself. The useful takeaway is that switching the request path to a reactive execution model with Mutiny keeps I/O waits off the worker threads, allowing a small fixed number of I/O threads to drive many concurrent requests.

The Decision: Reactive Execution vs. Blocking Execution

Quarkus supports two primary execution paths for HTTP endpoints. The classic blocking path uses a worker thread pool and is straightforward to write with synchronous Java code. The reactive path uses Mutiny, a reactive programming library integrated with Quarkus, where endpoints return Uni or Multi types. Uni represents an operation that emits zero or one item, such as a single database row. Multi represents a stream of zero or many items, such as a server-sent events feed. The decision is not simply that reactive is faster; it is whether your endpoint's dominant cost is I/O wait time that can be handled without blocking a thread.

Comparing Supported Options in Quarkus

Within Quarkus, the practical choice is between the classic RESTEasy extension and RESTEasy Reactive, and between blocking data sources and reactive data sources. The table below summarizes the supported combinations.

Trade-offs: When Reactive Helps and When It Hurts

Reactive execution improves resource utilization when requests spend most of their time waiting on network or disk I/O. Under simulated high concurrency, a reactive endpoint can sustain more in-flight requests with fewer threads. However, the benefit disappears if any call in the chain blocks. A single synchronous JDBC query or a blocking HTTP client inside a reactive endpoint will occupy an I/O thread and negate the non-blocking advantage. Reactive code also introduces composition overhead: developers must chain operations with onItem().transform() or similar operators rather than writing sequential statements. For CPU-intensive work, blocking code on a worker pool is often simpler and equally performant.

Concrete Implementation: A Reactive JAX-RS Endpoint

The following example assumes a recent Quarkus release with the RESTEasy Reactive and Reactive PostgreSQL extensions. It shows a resource that returns a Uni backed by a reactive database pool.

Adding Dependencies

Run the following command from the project root, where the Maven wrapper is available:

./mvnw quarkus:add-extension -Dextensions="resteasy-reactive,reactive-pg-client"

Where to run: project root directory. Required permissions: ability to modify pom.xml and download dependencies. Expected check: the extensions appear under Dependencies in pom.xml. Relevant risk: if the project pins an older Quarkus version, the extension coordinates may differ; verify compatibility before upgrading.

Configuring the Reactive Datasource

Add the following to src/main/resources/application.properties:

quarkus.datasource.reactive.url=vertx-reactive:postgresql://localhost/mydb
quarkus.datasource.username=appuser
quarkus.datasource.password=secret

Where to run: standard Quarkus resource directory. Expected check: the application starts without datasource validation errors. Relevant risk: using a blocking JDBC URL with a reactive endpoint forces blocking behavior and can cause thread starvation under load.

Writing the Resource

Create the resource class in src/main/java/com/example/DataResource.java:

package com.example;

import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/data")
public class DataResource {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Uni<String> getData() {
        return Uni.createFrom().item("{\"status\":\"ok\"}");
    }
}

Where to run: standard Java source tree. Expected check: the application compiles and the endpoint responds without requiring a worker thread to block on the returned Uni.

Validating Non-Blocking Behavior

Start the application in development mode from the project root:

./mvnw quarkus:dev

In a separate terminal, send a request:

curl -s http://localhost:8080/data

Expected check: the response body contains the JSON payload. To confirm asynchronous execution flow, inspect the application logs for event-loop thread names rather than names from the worker thread pool. Under load, a reactive endpoint should show stable thread counts while request volume increases. A practical way to check is to run a load generator such as wrk or JMeter against the endpoint and monitor the JVM thread count via JFR or jstack; sustained request throughput without growing worker threads indicates the reactive path is active.

Limitations and Version Considerations

Reactive endpoints require every downstream dependency to offer a non-blocking client. If a legacy library only exposes a synchronous API, you must isolate it with @Blocking or run it on a worker thread, which reintroduces blocking. Quarkus version differences matter: RESTEasy Reactive is the recommended HTTP layer in recent Quarkus releases, while older projects may still use the classic RESTEasy extension where reactive return types behave differently. Always verify the exact extension versions in your pom.xml and consult the current Quarkus guides for your release, because configuration property names and default thread pool sizes can change between minor versions.