Vert.x HTTP Server and Event Bus: Per‑Handler Worker Pool Configuration Decision

Answer the Question First

Exposing a per‑handler worker‑pool API is beneficial when a subset of HTTP handlers performs blocking I/O and publishes to a shared Event‑Bus address. Dedicated pools isolate those handlers from the global pool, preventing one blocking consumer from starving others and improving latency predictability. However, each pool consumes JVM threads, so you must balance isolation against overall thread count and system resources.

Confirmed Facts

• Vert.x 4.x defaults to Math.max(20, availableProcessors * 2) worker threads per global pool.
• Consumers can set ConsumerOptions.setWorkerPoolSize() to create a dedicated pool for that consumer.
• Worker verticles can be deployed with WorkerDeploymentOptions specifying workerPoolSize and workerPoolName.
• Event‑Bus delivery is sequential per address; high publish rates can queue when the consumer’s pool is saturated.
• Vert.x warns when a pool exceeds 1,000 threads.

Impact on Latency and Isolation

• Latency predictability improves because the dedicated pool’s queue length is independent of other handlers.
• Resource isolation is achieved: a long‑running blocking task in one handler does not affect the event‑loop or other workers.
• However, if the dedicated pool is too small, its own queue will grow, negating the benefit.
• Large pools can increase context‑switch overhead and consume CPU cores, potentially degrading overall throughput.

Back‑Pressure Model Changes

• Each dedicated pool should expose its own queueSize metric via the Vert.x metrics endpoint.
• Applications can apply back‑pressure by rejecting or buffering HTTP requests when a pool’s queue exceeds a threshold.
• The global pool’s back‑pressure remains unchanged; only the per‑handler pool’s limits need monitoring.

Implementation Steps for Your Use Case

1. Identify the HTTP handlers that perform blocking work and publish to the shared address.

2. Decide on a dedicated pool size. A good starting point is the number of concurrent requests you expect to hit that handler plus a safety margin (e.g., maxConcurrent + 2).

3. Deploy the handler as a worker verticle with WorkerDeploymentOptions:

   Vertx vertx = Vertx.vertx();
   WorkerDeploymentOptions opts = new WorkerDeploymentOptions()
       .setWorkerPoolSize(10)      // adjust per load
       .setWorkerPoolName("blocking-http-pool");
   vertx.deployVerticle(new BlockingHttpHandler(), opts);
   

4. For consumers that need isolation, set ConsumerOptions.setWorkerPoolSize() and optionally setWorkerPoolName():

   EventBus eb = vertx.eventBus();
   eb.consumer("shared.address", msg -> {
       // blocking logic
   }).handlerOptions(new ConsumerOptions()
       .setWorkerPoolSize(5)
       .setWorkerPoolName("consumer-pool"));
   

5. Expose the metrics endpoint (/metrics) and monitor vertx.worker.pool.*.queue.size and vertx.worker.pool.*.activeThreads for each pool.

6. Run a load test simulating the expected concurrent request volume. Observe event‑loop latency and queue lengths. Adjust pool sizes if you see spikes or long queues.

7. Implement back‑pressure: if a pool’s queue exceeds a configurable threshold, return a 503 or queue the request in an external buffer.

8. Ensure the sum of all worker pool sizes stays below the JVM’s thread limit (typically maxRAM / 2MB minus event‑loop threads).

Diagnostic Detail Needed

To refine the pool‑size recommendation, please provide the maximum number of concurrent HTTP requests you expect to handle per second for the blocking handlers. This figure directly influences the optimal pool size and the back‑pressure threshold.