> ## Content Index > Fetch the complete content index at: https://www.ggorantala.dev/llms.txt > Use this file to discover other available public pages before exploring further. # How to Configure a Thread Pool With ExecutorService in Java - URL: https://www.ggorantala.dev/how-to-configure-thread-pool-executorservice-java-2/ - Published: 2026-08-21T03:25:00.000Z - Updated: 2026-10-31T04:29:33.000Z - Description: Build a bounded thread pool for a support-ticket desk in Java 21: pick the size, cap the queue, name threads, count rejections, and shut down cleanly. - Author: Gopi Gorantala - Tags: java-concurrency, java-tutorials, how-to-tutorials ## Ten tickets fit, four don't This is a thread pool for a support desk with four agents and room for six waiting tickets. I threw fourteen tickets at it at once: ```log -- 14 tickets arrive at once (4 agents + 6 waiting = 10 fit) -- after ticket 4: pool=4 active=4 queued=0 done=0 after ticket 10: pool=4 active=4 queued=6 done=0 ticket 11 REJECTED: desk is full: 4 busy, 6 waiting ticket 12 REJECTED: desk is full: 4 busy, 6 waiting ticket 13 REJECTED: desk is full: 4 busy, 6 waiting ticket 14 REJECTED: desk is full: 4 busy, 6 waiting [... lines cut] closed cleanly=true ok=9 failed=1 rejected=4 largestPool=4 ``` Nothing ran away. Ten tickets were accepted, four were turned down loudly, one ticket that threw an exception was counted instead of vanishing, and the pool shut down without leaving a thread behind. That's what "configure a thread pool in Java" should mean: you decide how many threads, how much waiting room, what happens when both are full, and how it all stops. The defaults in `Executors.newFixedThreadPool(4)` quietly decide two of those four for you, and not in your favour (more on that below). You'll build this in plain Java 21, about 370 lines across seven small files, with no libraries. It's for you if you've used `new Thread(...)` or `executor.submit(...)` and now want a pool you'd be happy to see in a production service. Knowing what a lambda is and what `Future.get()` does is enough. The build took me two rounds of compiling. The first draft of the rejection counter used a pair of one-element arrays to smuggle a reference past the constructor. It was ugly, I rewrote it before it ran, and the version below is the one that compiled first time. ## Check your setup | Tool | Version I used | Check it with | | --------- | -------------------------------- | ---------------- | | JDK | OpenJDK 21.0.12.1 (Ubuntu build) | java -version | | Gradle | 8.14.3 | gradle --version | | Machine | 2 vCPUs, Linux | nproc | | Libraries | none | n/a | Java 19 or later is needed for one nicety (`ExecutorService` implementing `AutoCloseable`, used in `Sizing.java`). Everything else runs on Java 11, with `record` and the `switch` arrows being the exceptions: those need 16 and 14. Limits, up front. My build environment couldn't reach Maven Central, so the checks are plain Java with a PASS or FAIL line each, not JUnit; each one maps straight onto a JUnit 5 `@Test`. I ran Gradle with `--offline` (there's nothing to download). I didn't open IntelliJ IDEA or Eclipse, so the IDE steps are from the vendors' documentation and labelled that way. And I ran on JDK 21 only. ## Create the ticket-desk project (javac, Gradle, IntelliJ IDEA, Eclipse) I used the command line with Gradle as the main path. Make the folders and two build files: ```bash mkdir -p desk/src/main/java/com/example/desk cd desk ``` `settings.gradle.kts`: ```kotlin rootProject.name = "desk" ``` `build.gradle.kts`: ```kotlin plugins { java application } java { toolchain { languageVersion = JavaLanguageVersion.of(21) } } repositories { mavenCentral() } // nothing to download; JUnit would come from here tasks.withType { options.compilerArgs.add("-Xlint:all") } application { // pick the demo with: gradle -q run -Pmain=com.example.desk.Checks mainClass = providers.gradleProperty("main").orElse("com.example.desk.Main") } ``` `-Xlint:all` makes the compiler grumble about anything suspicious, and I want that now rather than in review. The `main` property lets one build file run every demo in this article: `gradle -q run -Pmain=com.example.desk.Checks`. Without `-P` it runs `Main`. The tree when you're finished: ```log desk/ ├── build.gradle.kts ├── settings.gradle.kts └── src/main/java/com/example/desk/ ├── Ticket.java ├── NamedThreadFactory.java ├── DeskPool.java ├── Main.java ├── Sizing.java ├── Traps.java └── Checks.java ``` ### With plain javac No build tool at all works too: ```bash javac -Xlint:all -d out $(find src -name '*.java') java -cp out com.example.desk.Main ``` Silence from `javac` is a clean compile. I ran this as well; the checks gave the same result. (On Windows PowerShell, list the files explicitly instead of using `$(find ...)`; I didn't test that.) ### In IntelliJ IDEA *Verified from the docs, not executed.* **File → New → Project…**, pick **Java**, set the build system to **Gradle** with **Kotlin** as the DSL and JDK 21, call it `desk`, then paste in the files. Any class with a `main` method gets a green arrow in the gutter. ### In Eclipse *Verified from the docs, not executed.* Use **File → Import → Gradle → Existing Gradle Project** (Buildship ships with the common Eclipse packages; install it from the Marketplace if yours lacks it) and point it at the `desk` folder. Run a class with **Run As → Java Application**. ### Podman and Docker Not needed. Everything runs inside one JVM. ## How to configure a thread pool with ExecutorService, one decision at a time A pool is five decisions: how many threads, how many tickets may wait, what to do when both are full, what the threads are called, and how to stop. The `Executors` factory methods make some of those for you. We'll make all of them ourselves, one step each. ### Step 1: Describe the work **Goal:** a task that takes a known time and can be told to fail, so the pool has something to chew on. `src/main/java/com/example/desk/Ticket.java`: ```java package com.example.desk; /** One support ticket. workMs is how long the agent takes; fails=true makes the work throw. */ public record Ticket(int id, String customer, int workMs, boolean fails) { public Ticket(int id, String customer, int workMs) { this(id, customer, workMs, false); } /** Pretend to work on the ticket. */ public String resolve() throws InterruptedException { Thread.sleep(workMs); if (fails) { throw new IllegalStateException("ticket " + id + " from " + customer + " could not be resolved"); } return "ticket " + id + " resolved by " + Thread.currentThread().getName(); } } ``` `workMs` is how long the agent "works" (a `Thread.sleep`, standing in for a database call or an HTTP request). `fails = true` makes `resolve()` throw, which we'll need in Step 4\. The second constructor keeps the happy-path call short. ### Step 2: Name your threads **Goal:** every thread in the pool says who it is in logs and thread dumps. `src/main/java/com/example/desk/NamedThreadFactory.java`: ```java package com.example.desk; import java.util.concurrent.ThreadFactory; import java.util.concurrent.atomic.AtomicInteger; /** Gives every pool thread a readable name: desk-1, desk-2, ... */ public final class NamedThreadFactory implements ThreadFactory { private final String prefix; private final AtomicInteger counter = new AtomicInteger(1); // a field, not a new one per call public NamedThreadFactory(String prefix) { this.prefix = prefix; } @Override public Thread newThread(Runnable r) { Thread t = new Thread(r, prefix + "-" + counter.getAndIncrement()); t.setDaemon(false); // a pool nobody shuts down should be loud, not silent return t; } } ``` The default factory names threads `pool-1-thread-1`, which tells you nothing at 3 a.m. when you're looking at a dump with six pools in it. The counter is a **field**. I've seen this class written with `new AtomicInteger()` inside `newThread`, which gives every thread the name `agent-1`; a pool where every thread has the same name is close to undebuggable. `setDaemon(false)` is the default anyway. I wrote it out so the next line of this article makes sense: threads like these keep the JVM alive until you shut the pool down. ### Step 3: Build the pool **Goal:** a `ThreadPoolExecutor` with a fixed number of threads, a bounded queue, a rejection policy, and counters. `src/main/java/com/example/desk/DeskPool.java`: ```java package com.example.desk; import java.util.concurrent.ArrayBlockingQueue; import java.util.concurrent.ExecutionException; import java.util.concurrent.Future; import java.util.concurrent.RejectedExecutionException; import java.util.concurrent.RejectedExecutionHandler; import java.util.concurrent.ThreadPoolExecutor; import java.util.concurrent.TimeUnit; import java.util.concurrent.CancellationException; import java.util.concurrent.atomic.AtomicInteger; /** * The ticket desk's thread pool: fixed number of threads, a bounded queue, * and counters for the two things you want to alert on: rejections and failures. */ public final class DeskPool extends ThreadPoolExecutor { private final AtomicInteger failed = new AtomicInteger(); private final AtomicInteger completed = new AtomicInteger(); /** What to do when both the threads and the queue are full. */ public enum Overload { ABORT, CALLER_RUNS } /** Counts a rejection, then applies the real policy. */ private static final class CountingHandler implements RejectedExecutionHandler { final AtomicInteger count = new AtomicInteger(); final Overload mode; CountingHandler(Overload mode) { this.mode = mode; } @Override public void rejectedExecution(Runnable r, ThreadPoolExecutor ex) { count.incrementAndGet(); if (ex.isShutdown()) { throw new RejectedExecutionException("desk is closed"); } switch (mode) { case ABORT -> throw new RejectedExecutionException("desk is full: " + ex.getPoolSize() + " busy, " + ex.getQueue().size() + " waiting"); case CALLER_RUNS -> r.run(); // the submitting thread does the work itself } } } private final CountingHandler handler; public DeskPool(String name, int threads, int queueSize, Overload mode) { this(name, threads, queueSize, new CountingHandler(mode)); } private DeskPool(String name, int threads, int queueSize, CountingHandler handler) { super(threads, threads, // core == max: the queue decides, so don't pretend otherwise 0L, TimeUnit.MILLISECONDS, new ArrayBlockingQueue<>(queueSize), // bounded, so overload becomes visible new NamedThreadFactory(name), handler); this.handler = handler; } @Override protected void afterExecute(Runnable r, Throwable t) { super.afterExecute(r, t); Throwable problem = t; // submit() wraps the task in a FutureTask, which swallows the exception. Dig it out. if (problem == null && r instanceof Future f && f.isDone()) { try { f.get(); } catch (CancellationException e) { problem = e; } catch (ExecutionException e) { problem = e.getCause(); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } } if (problem != null) { failed.incrementAndGet(); System.out.println(" [" + Thread.currentThread().getName() + "] FAILED: " + problem.getMessage()); } else { completed.incrementAndGet(); } } public int rejectedCount() { return handler.count.get(); } public int failedCount() { return failed.get(); } public int okCount() { return completed.get(); } public String snapshot() { return "pool=" + getPoolSize() + " active=" + getActiveCount() + " queued=" + getQueue().size() + " done=" + getCompletedTaskCount(); } } ``` This is the heart of the article, so here's what each choice does. - `super(threads, threads, ...)`: core size equals maximum size. I'll explain in "Why the queue decides" why a different maximum usually does nothing. - `new ArrayBlockingQueue<>(queueSize)`: bounded. When it fills, the *next* submit is refused. An unbounded queue never refuses anything, and that is how a slow database turns into an out-of-memory error an hour later. - `Overload.ABORT` throws `RejectedExecutionException` to the caller, who can return a 503\. `Overload.CALLER_RUNS` makes the submitting thread do the work itself, which slows the producer down. Both count the rejection first. - `afterExecute` is the part people miss. When you call `submit(...)`, the pool wraps your task in a `FutureTask`, and the `FutureTask` swallows any exception until somebody calls `get()`. Without this method, a failing task fails in silence. The method digs the exception out of the finished future and counts it. If you want a bit more on the rules the pool follows, [ThreadPoolExecutor explained](https://ggorantala.dev/java-threadpoolexecutor/?ref=ggorantala.dev) takes it apart with lab output. Here we use it. **Checkpoint:** compile with `gradle --offline -q compileJava`. No output means a clean build. If you pass `true` instead of an `Overload` value somewhere, you'll get this, and I forced it to be sure: ```log Bad.java:2: error: no suitable constructor found for DeskPool(String,int,int,boolean) constructor DeskPool.DeskPool(String,int,int,Overload) is not applicable (argument mismatch; boolean cannot be converted to Overload) ``` ### Step 4: Open the desk **Goal:** submit fourteen tickets to four agents and see all four outcomes (running, waiting, rejected, failed). `src/main/java/com/example/desk/Main.java`: ```java package com.example.desk; import java.util.ArrayList; import java.util.List; import java.util.concurrent.ExecutionException; import java.util.concurrent.Future; import java.util.concurrent.RejectedExecutionException; import java.util.concurrent.TimeUnit; public class Main { public static void main(String[] args) throws Exception { // 4 agents, room for 6 waiting tickets, then the desk says no. DeskPool desk = new DeskPool("agent", 4, 6, DeskPool.Overload.ABORT); List> receipts = new ArrayList<>(); System.out.println("-- 14 tickets arrive at once (4 agents + 6 waiting = 10 fit) --"); for (int id = 1; id <= 14; id++) { Ticket t = new Ticket(id, "customer-" + id, 300, id == 3); // ticket 3 will blow up try { receipts.add(desk.submit(t::resolve)); } catch (RejectedExecutionException e) { System.out.printf("ticket %2d REJECTED: %s%n", id, e.getMessage()); } if (id == 4 || id == 10 || id == 11) { System.out.printf("after ticket %2d: %s%n", id, desk.snapshot()); } } System.out.println("-- collecting results --"); for (Future f : receipts) { try { System.out.println(f.get()); } catch (ExecutionException e) { System.out.println("caller sees: " + e.getCause()); } } desk.shutdown(); // stop taking tickets, finish the queue boolean clean = desk.awaitTermination(5, TimeUnit.SECONDS); // wait, but not forever System.out.printf("closed cleanly=%b ok=%d failed=%d rejected=%d largestPool=%d%n", clean, desk.okCount(), desk.failedCount(), desk.rejectedCount(), desk.getLargestPoolSize()); } } ``` Two lines are doing the real work. `desk.submit(t::resolve)` hands the pool a `Callable` and returns a `Future` you can ask about later. `desk.awaitTermination(5, TimeUnit.SECONDS)` waits for the pool to drain, but only for five seconds; a shutdown that waits forever is a hang in waiting. ## See what 14 tickets do to 4 agents ```bash gradle --offline -q run ``` ```log -- 14 tickets arrive at once (4 agents + 6 waiting = 10 fit) -- after ticket 4: pool=4 active=4 queued=0 done=0 after ticket 10: pool=4 active=4 queued=6 done=0 ticket 11 REJECTED: desk is full: 4 busy, 6 waiting after ticket 11: pool=4 active=4 queued=6 done=0 ticket 12 REJECTED: desk is full: 4 busy, 6 waiting ticket 13 REJECTED: desk is full: 4 busy, 6 waiting ticket 14 REJECTED: desk is full: 4 busy, 6 waiting -- collecting results -- ticket 1 resolved by agent-1 ticket 2 resolved by agent-2 caller sees: java.lang.IllegalStateException: ticket 3 from customer-3 could not be resolved ticket 4 resolved by agent-4 [agent-3] FAILED: ticket 3 from customer-3 could not be resolved ticket 5 resolved by agent-2 ticket 6 resolved by agent-4 ticket 7 resolved by agent-1 ticket 8 resolved by agent-3 ticket 9 resolved by agent-4 ticket 10 resolved by agent-2 closed cleanly=true ok=9 failed=1 rejected=4 largestPool=4 ``` Read it top to bottom. After ticket 4 the pool has four threads and an empty queue: each of the first four tickets got its own thread. After ticket 10, still four threads, and six tickets waiting. Tickets 11 to 14 are rejected with a message that says what the desk looked like at that moment. That message is the one I'd want in a log. Ticket 3 is the failure. Notice "caller sees" prints *before* the `[agent-3] FAILED` line. The caller learns about the exception when it calls `get()`, which can happen before the pool thread finishes its own bookkeeping in `afterExecute`. Don't rely on the order of those two lines. And the final line: `ok=9 failed=1 rejected=4`. Ten accepted tickets, nine resolved and one failed, and four turned away. `largestPool=4` confirms the pool never grew past what we configured. ### How many threads should it have? The honest answer is "it depends what the work is doing". `Sizing.java` runs 48 tickets through pools of different sizes, once with tickets that *wait* (a 100 ms sleep, like a network call) and once with tickets that *compute* (a tight arithmetic loop). `src/main/java/com/example/desk/Sizing.java`: ```java package com.example.desk; import java.util.ArrayList; import java.util.List; import java.util.concurrent.Callable; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; /** Same 48 tickets, different pool sizes. Two workloads: waiting (sleep) and number-crunching. */ public class Sizing { static long spin(long iterations) { long x = 0; for (long i = 0; i < iterations; i++) x += i ^ (x >>> 3); return x; } static long run(int threads, Callable