I Built My Own Java Concurrency Engine. It Got a Little Out of Hand.
I was learning Java threads. At some point, the usual examples started feeling a little too polite. Create a thread, print something, join it, congratulations, everyone goes home.
But what happens when an application has a lot of work to do? Who decides which task runs first? What happens when the queue is full, a task fails, someone cancels it, or the whole engine needs to shut down without leaving work stranded?
I wanted to understand those problems by building the machinery myself. So I made ThreadStorm: a custom Java task execution engine built around a bounded task queue and a pool of reusable worker threads.
The goal was never to replace Java's concurrency libraries. It was to stop treating concurrency like a collection of magic methods and understand what an execution system actually has to manage.
This is the story of how that happened, what ThreadStorm can do, what it absolutely cannot do, and why my benchmark results humbled me just enough to keep the project interesting.
01 · Why I Built This
Learning threads individually is one thing. Coordinating a bunch of them without accidentally creating a tiny disaster is another.
A thread is an execution path. A task is a unit of work. They are related, but they are not the same thing. If every incoming task gets its own brand-new thread, the application has to deal with thread creation costs, resource limits and lifecycle management over and over again.
A worker pool gives us a different model: create a fixed number of workers, give them work from a shared queue, and let them keep going until the engine shuts down.
Java already provides ExecutorService, which does this kind of job very well.
I could have just used that and moved on with my life. Unfortunately, that would have defeated
the point of the exercise.
I wanted to implement the queue, worker lifecycle, scheduling rules, task tracking and failure handling myself. Basically, I wanted to find out how many ways a few threads can make you question your life choices.
02 · What Is ThreadStorm, Exactly?
ThreadStorm is a small task execution engine. An application submits tasks to it, the engine places accepted tasks into a bounded queue, and a fixed pool of workers takes those tasks and executes them.
The important word here is bounded. The queue has a maximum capacity. Without a limit, a producer could keep submitting work faster than workers can process it until the application runs out of memory. ThreadStorm makes queue pressure an explicit part of the API.
YOUR APPLICATION
|
| submit(task, priority)
v
+-----------------------+
| THREADSTORM |
| |
| lifecycle + metrics |
+-----------+-----------+
|
v
+-----------------------+
| BOUNDED TASK QUEUE |
| |
| CRITICAL / HIGH |
| NORMAL / LOW |
| priority aging |
+-----------+-----------+
|
+--------+--------+
| | |
v v v
Worker 1 Worker 2 Worker 3
| | |
+--------+--------+
|
v
TASK RESULT / STATUS
| |
v v
METRICS DEAD LETTER
QUEUE (failed)
A worker does not need to know where a task came from. It takes the next eligible task, executes it, updates its state and moves on. The application does not need to manage individual worker threads either. It talks to the engine through task submissions and task handles.
The main pieces
ThreadStormis the public engine facade and owns the lifecycle.TaskQueuestores pending work and decides which task should be taken next.Workeris a reusable thread that takes and executes tasks.TaskHandlelets the caller inspect, await or cancel an accepted task.TaskContextgives a running task information about its execution and cooperative checkpoints.MetricsCollectorrecords task and worker activity.DeadLetterQueueretains tasks that have exhausted their retry attempts.
03 · Workers, Queues and the Producer–Consumer Problem
The core of ThreadStorm is a classic producer–consumer setup. The application is the producer: it submits work. The workers are consumers: they wait for work, take it from the queue and execute it.
The queue is shared state, which means multiple threads may try to interact with it at the same time. That is where synchronization matters.
ThreadStorm's queue uses synchronized methods and the monitor's wait() and
notifyAll() mechanism. A worker that finds the queue empty waits instead of spinning
in a loop and burning CPU. When a task is submitted, waiting workers are notified.
while (!isInterrupted()) {
TaskEnvelope task = queue.take();
if (task == null) {
break;
}
if (!task.getHandle().tryStart(getName())) {
continue;
}
execute(task);
}
This is deliberately simplified, but it captures the shape of the worker loop. The actual worker also handles retries, cancellation, timeouts, status transitions, metrics and dead-letter recording.
Why a fixed worker pool?
Suppose an application submits 100 tasks and the engine has 4 workers. At most 4 tasks are executing at a time. The remaining tasks wait in the queue until a worker becomes available. The engine reuses those same 4 threads instead of creating 100 threads.
100 submitted tasks
|
v
+-----------------------+
| TASK QUEUE |
+-----------------------+
|
+----+----+----+
| | | |
v v v v
W1 W2 W3 W4
Only four tasks execute at once.
The rest wait for an available worker.
More threads are not automatically better. Threads have overhead, and the machine still has a finite number of CPU cores and other resources. The useful worker count depends on the workload.
04 · Priority Scheduling, Without Letting LOW Wait Forever
Not every task is equally urgent. A task queue that treats every task identically is simple, but sometimes an application needs important work to be picked up first.
ThreadStorm supports four priorities:
CRITICAL -> highest priority
HIGH
NORMAL
LOW -> lowest priority
The queue selects the task with the highest effective priority. If two tasks have the same effective priority, the earlier enqueued task wins.
But there is a problem with priority queues: starvation. If high-priority work keeps arriving, a low-priority task could sit there forever.
ThreadStorm uses priority aging. Every configured aging interval that a task waits, its effective priority moves up one level, up to the highest level. The default interval in the queue is five seconds.
A LOW task waits...
After one aging interval: NORMAL
After two intervals: HIGH
After three intervals: CRITICAL
Eventually, waiting work gets a chance.
This is a small scheduling policy, not a magical fairness guarantee under every possible workload. But it makes the trade-off explicit: urgent work gets preference, while older work gradually gets promoted.
05 · A Task Is More Than a Runnable
Submitting work and forgetting about it is fine for some fire-and-forget jobs. But a useful task engine should let the caller ask: did my task run? Is it still waiting? Did it fail? Can I cancel it?
That's what TaskHandle is for. Every accepted task gets a handle with an ID, a status,
timestamps, attempt count, worker name and failure information.
QUEUED
|
v
RUNNING
/ | \
/ | \
v v v
SUCCEEDED FAILED CANCELLED
The state is managed with an AtomicReference, and transitions use compare-and-set
operations. That matters because cancellation and worker execution can race with each other.
We don't want two threads casually deciding the same task has two different outcomes.
The handle also exposes a CompletionStage, so callers can react to completion
asynchronously instead of always blocking a thread while waiting.
06 · Using ThreadStorm
The public API is intentionally small. Create an engine, start it, submit tasks, inspect their handles if needed, and shut the engine down when you're finished.
import core.Priority;
import core.ThreadStorm;
import task.TaskHandle;
public class Demo {
public static void main(String[] args) throws InterruptedException {
ThreadStorm engine = new ThreadStorm(3, 10);
engine.start();
try {
for (int i = 1; i <= 5; i++) {
final int taskNumber = i;
TaskHandle handle = engine.submit(context -> {
System.out.println(
"Task " + taskNumber +
" running on " + context.getWorkerName()
);
Thread.sleep(1000);
System.out.println("Task " + taskNumber + " finished");
}, Priority.NORMAL);
System.out.println("Submitted " + handle.getId());
}
} finally {
engine.shutdown();
}
}
}
Here, the engine has three workers and a queue capacity of ten. Five tasks are submitted. Up to three can run at once; the others wait for a worker. The default submission policy blocks when the queue is full until capacity becomes available.
The shutdown() call stops new submissions, closes the queue and waits for accepted
queued work to drain before the workers terminate. In other words, it is a graceful shutdown,
not an abrupt "good luck everybody" situation.
07 · When Tasks Fail, Get Cancelled or Take Too Long
Real work fails. A network request times out, a file is missing, an API returns an error, or somebody writes a task that throws an exception. An execution engine needs a policy for that.
Retries and backoff
ThreadStorm supports configurable retry policies. A policy specifies the maximum number of retries, an initial delay and a multiplier for exponential backoff.
RetryPolicy retry = new RetryPolicy(
3, // maximum retries
1000, // initial delay in milliseconds
2.0 // backoff multiplier
);
With those settings, retries are delayed by approximately 1, 2 and 4 seconds. The original task remains one logical task, while its attempt count increases. If it still fails after exhausting its retries, ThreadStorm marks it failed, records the failure and adds an entry to the Dead Letter Queue.
Cancellation
A queued task can be marked cancelled before a worker starts it. A running task is different: Java does not provide a safe general-purpose way to forcibly stop arbitrary code running on a thread.
ThreadStorm therefore uses cooperative cancellation. A running task can check
its TaskContext at checkpoints. If cancellation has been requested, the checkpoint
throws a cancellation exception and the task can stop.
engine.submit(context -> {
while (hasMoreWork()) {
context.checkpoint();
processNextChunk();
}
}, Priority.NORMAL);
Execution timeouts
Tasks can also be given an execution timeout. This is cooperative too: the timeout is detected when the task reaches a checkpoint. It does not forcibly kill a worker or interrupt arbitrary blocking code. That distinction is important, and I would rather be clear about it than claim ThreadStorm can do something Java intentionally makes difficult.
08 · Groups and Dependencies
Sometimes tasks are related. You might submit a batch of independent jobs and want to wait for all of them, or you might have a sequence where one task should only run after another succeeds.
TaskGroup provides a way to collect related handles, inspect their statuses,
cancel the group or wait for all its current tasks to finish.
ThreadStorm also supports submitAfter() for task dependencies. It waits on the
dependency completion stages rather than parking one of the engine's workers just to wait.
The dependent task is submitted only after all dependencies have completed successfully.
TaskHandle download = engine.submit(
context -> downloadFile(),
Priority.HIGH
);
engine.submitAfter(
List.of(download),
context -> processFile(),
Priority.NORMAL
);
If the dependency does not succeed, the dependent task is not submitted. That keeps the dependency rule explicit instead of hiding it inside a sleeping worker.
09 · I Also Wanted to See What Was Happening
A concurrency engine is much harder to reason about if all you get is a final "done" message. I wanted to see what workers were doing while the engine was running.
ThreadStorm's metrics collector records submitted, started, completed, failed, retried and cancelled tasks, along with queue wait time and execution time. It also tracks worker states and recent task events.
Then I built a terminal dashboard around those metrics. It has multiple pages for engine activity, workers, queue state, task history, failures and related information. There is also a simpler text CLI for terminals where a full-screen interface is not behaving.
The dashboard is not the engine. It is a view into the engine, which means the task execution core can be used without opening the TUI at all.
# Full terminal dashboard
.\run.ps1
# Simpler text interface
.\run.ps1 -Cli
# Run the bundled test suite
.\run.ps1 -Test
# Start with custom worker and queue counts
.\run.ps1 -Dashboard --workers 4 --capacity 128
The project targets Java 17 or newer and does not require external Java dependencies. On Windows, the launcher also selects a JDK 17+ for both compilation and execution, which saved me from a few rounds of arguing with mismatched Java installations.
10 · Testing the Things That Can Go Wrong
Concurrency bugs are especially annoying because a program can appear to work ten times and fail on the eleventh run when two operations happen in a different order.
The project includes tests for priority scheduling, fault tolerance, observability, task coordination, lifecycle handling, cancellation, TUI integration, benchmark smoke tests and a stress test.
.\run.ps1 -Test
The tests cover more than whether a task can print a message. They exercise transitions, shutdown behaviour, retries, cancellation races and the integration between the engine and its dashboard.
That does not prove the absence of every possible concurrency bug. It does mean the project has a repeatable test suite for the behaviours I intended to support.
11 · Benchmarking: Java's ExecutorService Is Annoyingly Good
I included a small benchmark runner to compare three ways of executing the same deterministic, CPU-bound workload:
- Sequential execution on the calling thread.
- A fixed-size Java
ExecutorService. - ThreadStorm using the same worker count.
The checked-in benchmark results use 2,000 tasks, 20,000 integer-mixing iterations per task, one warm-up and three measured runs. Here are the median results from those three runs:
| Implementation | Median time | Median tasks/s |
|---|---|---|
| Sequential | 112.29 ms | 17,811.5 |
| ExecutorService | 31.31 ms | 63,872.1 |
| ThreadStorm | 42.20 ms | 47,396.6 |
In this particular run, both concurrent approaches beat sequential execution. ThreadStorm
processed more tasks per second than the sequential version, but it did not beat
ExecutorService. The JDK implementation was roughly 1.35 times faster by
throughput in this dataset.
And that's completely fine. ThreadStorm does more bookkeeping around each task: it creates handles and envelopes, updates atomic states, records metrics, applies scheduling rules and coordinates its own queue. That functionality has a cost.
The benchmark does not prove that ThreadStorm is faster than Java's executor. It shows that this implementation can execute concurrent work, while making the overhead of its extra machinery visible.
There are limitations here. This is a small, dependency-free comparative harness, not a publication-quality microbenchmark. It uses one machine, one workload shape and three measured runs. A serious performance comparison needs more workload types, more repetitions, careful environment control and a proper tool such as JMH.
I would rather publish an honest result where the standard library wins than manufacture a graph where my project wins. The point was to learn, not to defeat a class from the JDK in a benchmark cage match.
12 · What I Actually Learned
The biggest lesson was that multithreading is not just about starting multiple threads. The difficult part is coordinating shared state and defining what should happen when operations overlap.
I got a much more concrete understanding of the producer–consumer pattern, monitor-based synchronization, atomic state transitions, worker pools, task scheduling and lifecycle management. I also learned that cancellation is a protocol between the engine and the task, not a magic button that safely kills arbitrary Java code.
Another lesson: adding features to a concurrency system is easy compared to making their interactions predictable. Cancellation can race with task startup. Shutdown can race with submission. A retry changes the task's lifecycle. Metrics need to stay consistent while all of this is happening.
And finally, building something yourself does not automatically make it better than the standard library. Sometimes the standard library is faster, more battle-tested and maintained by people who have spent a very long time thinking about the exact problem you just discovered. Rude, but fair.
13 · What ThreadStorm Is Not
ThreadStorm is a learning project and a custom execution engine, not a production-ready
replacement for ExecutorService, Spring's task execution facilities or a
distributed job queue.
It runs tasks inside one JVM. It does not persist tasks across process crashes, distribute work across machines, or provide durable exactly-once execution. Its cancellation and timeout behaviour is cooperative, and its benchmark suite is not a substitute for a dedicated benchmarking framework.
Those are not hidden footnotes. They are useful boundaries for understanding what the project currently demonstrates and what would need to change before using something like this for production workloads.
14 · Source Code
ThreadStorm is available on GitHub. The repository includes the engine, task abstractions, metrics, terminal interfaces, tests, launch scripts and benchmark runner.
→ Explore ThreadStorm on GitHub
threadstorm/
├── core/
│ ├── ThreadStorm.java
│ ├── Worker.java
│ ├── WorkerPool.java
│ ├── TaskQueue.java
│ ├── TaskEnvelope.java
│ └── RetryPolicy.java
├── task/
│ ├── Task.java
│ ├── TaskContext.java
│ ├── TaskHandle.java
│ └── TaskGroup.java
├── metrics/
├── cli/
├── benchmarks/
├── tests/
├── Main.java
├── run.ps1
└── README.md
I started ThreadStorm because I wanted to understand Java threads beyond creating them and watching a few print statements appear in a different order.
I ended up with a task queue, worker pool, scheduler, retry handling, metrics, a terminal dashboard and a much healthier respect for concurrency bugs.
Would I use it instead of ExecutorService in a production application? No.
Would I build it again to understand how task execution systems work? Absolutely.
Also, Java is better than C. I will not be taking questions from platze or r1ftzy at this time.