Skip to main content

Stop Leaking Threads: Java Structured Concurrency, from Preview to Final

Ashikur Rahman
Ashikur Rahman
Published 5 November 2026·11 min read
Share Article:
Stop Leaking Threads: Java Structured Concurrency, from Preview to Final

Structured concurrency means a task that starts child tasks must wait for them, and must clean them up, before it finishes. In Java, you do this with StructuredTaskScope. It is a preview feature in Java 25, and it will become final in Java 28.

The story in one minute#

Imagine you ask two friends to go to two shops. One brings your ID card. One brings your credit report.

Friend A comes back and says, "The ID shop is closed!" You go home. But friend B is still walking to the second shop. Nobody told B to stop. B comes back later, and the door is shut.

That is unstructured concurrency. Friend B is an orphan.

In structured concurrency, you stand at the door and wait. When A says "closed", you shout "B, come back!" You do not leave until both friends are back. Nobody is lost.

My example: a loan application#

My project is a small loan app. To approve a loan, I need two facts first:

  1. NID information (the national ID check).

  2. CIB information (the credit report).

These two calls do not depend on each other, so I run them at the same time. When both are ready, I call the loan service.

The old way: Future and an executor#

Here is my unstructured version.

private final ExecutorService executor = Executors.newCachedThreadPool();
public LoanInformation applyLoan(String nid, String amount)
       throws ExecutionException, InterruptedException {

   Future<NidInformation> nidInformationFuture =
           executor.submit(() -> nidService.getNidInformation(nid));
   Future<CibInformation> cibInformationFuture =
           executor.submit(() -> cibService.getCibInformation(nid));
   NidInformation nidInformation = nidInformationFuture.get();
   CibInformation cibInformation = cibInformationFuture.get();
   if (null == nidInformation || null == cibInformation) {
       throw new RuntimeException("NID or CIB information is not available");
   }
   return loanService.applyForLoan(nid, amount);
}

When everything works, it is fine.

The trouble starts when one task fails.

Problem 1: the orphan thread#

In my test, the NID call fails right away. The CIB call is slow. It sleeps for one second, like a real network call.

The request thread waits on nidInformationFuture.get(). That call throws, so the request ends and the user gets an error:

But nobody told the CIB task to stop. It is still running on a pool thread.

The request thread ends with HTTP 500 while the CIB task keeps running on a pool thread

I ran this same pattern as a small stand-alone test. I named the first thread like Tomcat names its request threads. This is the console:

[+  12ms] [pool-1-thread-1       ] Fetching NID information
[+ 133ms] [http-nio-8080-exec-1  ] ERROR request failed: Error occurred while fetching NID information
[+ 135ms] [http-nio-8080-exec-1  ] HTTP 500 sent to client
[+1013ms] [pool-1-thread-2       ] Fetching CIB information

Look at the last line. The client got its answer at 135 ms. The CIB work still finished at 1013 ms. That is almost one second of work for a request that is already dead.

In a real system, that wasted work can be a database call, a slow HTTP call, or a paid API call. Do it a thousand times a minute and you have a leak.

"But I can cancel with CompletableFuture!"#

I tried this too. My applyLoanAsync method cancels the other task by hand:

nidInformationFuture.exceptionally(ex -> {
   cibInformationFuture.cancel(true);
   if (ex instanceof CancellationException) {
       return null;
   } else {
       throw new CompletionException(ex);
   }
})

It is long, easy to get wrong, and it hides a trap. For CompletableFuture, cancel(true) does not interrupt the running thread.

Cleanup should not depend on every developer remembering to write it. It should be built in.

Problem 2: the tracing problem#

Now think about the people who run your app at night.

With a plain executor, the work runs on pool-1-thread-1 and pool-1-thread-2. These threads belong to the pool, not to your request. Nothing in the program says "this thread was started by request number 42".

So:

  • In logs, you see lines from pool threads and you must guess which request they belong to.

  • In a thread dump, you see a flat list of threads. You cannot see who started who.

  • When a task is an orphan, it looks like a random thread doing random work.

Compare that to a normal method call. If a method fails, the stack trace shows the caller, and the caller's caller. You can follow the path home. Plain threads break this path.

Structured concurrency repairs it. The child tasks live inside the parent's scope, so the program has a real tree: one parent, many children. Tools can read this tree. The JDK thread dump in JSON format (jcmd <pid> Thread.dump_to_file -format=json <file>) can show a scope and the subtasks inside it.

What structured concurrency is#

There is one simple rule:

If a task starts child tasks, the children must finish before the parent's block ends.

It is the same idea as a try block or a for loop. The code shape matches the run-time shape. You open a scope, start tasks, wait, use results, and close the scope.

The request thread opens a scope, forks two subtasks, joins, and the scope closes with no child left

The lifecycle has five steps:

Open, fork, join, get, close, with cancel paths for failure or timeout
  1. open: create the scope (pick a joiner, or use the default).

  2. fork: start a subtask. Each one runs in its own virtual thread by default.

  3. join: wait for the subtasks, following the joiner's rule.

  4. get: read each subtask's result.

  5. close: leave the block. try-with-resources does this for you. It also waits for any subtask that was cancelled, so none escape.

My first structured version#

public LoanInformation applyLoan(String nid, String amount)
       throws ExecutionException, InterruptedException {
   try (var scope = StructuredTaskScope.open()) {
       log.info("Start forking nid and cib  tasks ");
       Subtask<NidInformation> getNidSubTask =
               scope.fork(() -> nidService.getNidInformation(nid));
       Subtask<CibInformation> getCibSubTask =
               scope.fork(() -> cibService.getCibInformation(nid));
       scope.join();
       NidInformation nidInfo = getNidSubTask.get();
       CibInformation cibInfo = getCibSubTask.get();
       if (null == nidInfo || null == cibInfo) {
           throw new RuntimeException("NID or CIB information is not available");
       }
       log.info("Structured : end task forking and start applying for loan ");
       return loanService.applyForLoan(nid, amount);
   } catch (ExecutionException e) {
       Throwable cause = e.getCause();
       log.error("Error occurred while applying for loan", cause);
       throw e;
   }
}

Three things to notice:

  • StructuredTaskScope.open() with no joiner uses the default rule: wait for all subtasks, but stop everything if one fails.

  • I call scope.join() before get(). If you call get() too early, Java throws an IllegalStateException.

  • The scope lives in try-with-resources. When the block ends, the scope ends.

The two calls ran at the same time, so the answer takes about one second (the CIB sleep), not two.

The log messages come in this order:

Start forking nid and cib  tasks
Fetching NID information
Fetching CIB information
Structured : end task forking and start applying for loan
Applying for loan for NID: ... with amount: 7000
Fetching NID comes first because NID answers right away. CIB sleeps for one second first.

Error handling: no more orphans#

Now the same failure as before. NID fails fast, CIB is slow.

NID fails, the scope cancels CIB, join throws ExecutionException, and the scope closes after both children are done

What happens, step by step:

  1. The NID subtask ends in the FAILED state.

  2. The joiner sees the failure and cancels the scope.

  3. The CIB thread is interrupted. Its Thread.sleep throws InterruptedException. My CibService already catches that and logs a warning.

  4. scope.join() throws an ExecutionException. The real error is in getCause().

  5. The scope closes only after CIB has stopped.

This is the catch block I use:

} catch (ExecutionException e) {
   Throwable cause = e.getCause();
   log.error("Error occurred while applying for loan", cause);
   throw e;
}

The answer looks the same, but the inside is very different. In the old code, the CIB task ran for a full second after the request ended. Here, CIB is stopped before the method returns. No work is left behind.

Situation

What Java does

A subtask fails

The joiner decides. The default cancels the others.

You call get() before join()

IllegalStateException

You call get() on a failed subtask

An exception, not a result. Check state() first if needed.

The thread waiting in join() is interrupted

InterruptedException, and the scope is cancelled.

One more thing for Java 27 and later: the built-in joiners that throw now use ExecutionException, the same type as Future.get().

Joiners: the rule of the scope#

A joiner answers three questions:

  • When should the scope stop waiting?

  • When should it cancel the other subtasks?

  • What should join() return?

Together, these answers are the joiner policy.

Decision diagram: which joiner to use

Joiner

Policy

join() returns

awaitAllSuccessfulOrThrow() (default of open())

Wait for all. If one fails, cancel the rest and throw.

Nothing useful (null). Read each Subtask.

allSuccessfulOrThrow()

Wait for all. If one fails, cancel the rest and throw.

A List of all results

anySuccessfulOrThrow()

The first success wins. Cancel the rest. Throw only if all fail.

The first result

allUntil(predicate)

Keep going until your test says stop. Then cancel the rest.

The list of subtasks

Custom Joiner

Your own rule

Whatever you build

This is how I use Joiner.allSuccessfulOrThrow() :

try (var scope = StructuredTaskScope.open(Joiner.allSuccessfulOrThrow())) {
   log.info("Structured : start forking tasks ");
   Subtask<NidInformation> getNidSubTask =
           scope.fork(() -> nidService.getNidInformation(nid));
   Subtask<CibInformation> getCibSubTask =
           scope.fork(() -> cibService.getCibInformation(nid));
   log.info("nid state={}, cib state={}", getNidSubTask.state(), getCibSubTask.state());
   scope.join();
   // ... get() both results, then call the loan service
}

I print state() right after fork on purpose. A subtask can be UNAVAILABLE, SUCCESS, or FAILED. Right after fork, the work is not done yet, so there is no result to read. After join, you can trust the state.

Two more built-in joiners are worth a short look. These two snippets are small examples from the API.

First one wins (for example, ask two servers and use the fastest):

try (var scope = StructuredTaskScope.open(Joiner.<String>anySuccessfulOrThrow())) {
   scope.fork(() -> callServerA());
   scope.fork(() -> callServerB());
   String fastest = scope.join();   // the loser is cancelled
}

Stop on my own rule:

try (var scope = StructuredTaskScope.open(Joiner.<String>allUntil(s -> s.state() == Subtask.State.FAILED))) {
   scope.fork(() -> task1());
   scope.fork(() -> task2());
   var subtasks = scope.join();     // decide what to do with each one
}

A custom joiner: FailFirstJoiner#

Sometimes the built-in rules are not enough. I wanted a joiner that does one thing: remember the first failure and cancel everything else.

A joiner has a few methods:

  • onFork: called when a subtask starts. Return true to cancel the scope.

  • onComplete: called when a subtask ends. Return true to cancel the scope.

  • result: called when join() finishes. Return the answer, or throw.

  • timeout: called when the scope runs out of time.

Here is my FailFirstJoiner:

public class FailFirstJoiner implements StructuredTaskScope.Joiner {

   private final AtomicReference<Throwable> failure = new AtomicReference<>();

   @Override
   public boolean onFork(StructuredTaskScope.Subtask subtask) {
       return StructuredTaskScope.Joiner.super.onFork(subtask);
   }

   @Override
   public boolean onComplete(StructuredTaskScope.Subtask subtask) {
       if (subtask.state() == StructuredTaskScope.Subtask.State.FAILED) {
           failure.compareAndSet(null, subtask.exception());
           return true;   // cancel the other subtask
       }
       return false;      // keep waiting
   }

   @Override
   public Object result() throws Throwable {
       Throwable t = failure.get();
       if (t != null) throw t;
       return null;
   }

   @Override
   public Object timeout() throws Throwable {
       return null;
   }
}

How it works, in plain words:

  • onComplete runs each time a subtask ends.

  • If the subtask failed, I save the error (only the first one, because of compareAndSet) and return true. That means "cancel the rest".

  • If it did not fail, I return false. That means "keep waiting".

  • In result(), if I saved an error, I throw it. Otherwise I return null.

AtomicReference is needed because onComplete can be called from different threads at nearly the same time.

I use it like this:

try (var scope = StructuredTaskScope.open(new FailFirstJoiner())) {
   Subtask<NidInformation> nidTask = scope.fork(() -> nidService.getNidInformation(nid));
   Subtask<CibInformation> cibTask = scope.fork(() -> cibService.getCibInformation(nid));
   scope.join();
   if (nidTask.get() == null || cibTask.get() == null) {
       throw new RuntimeException("NID or CIB information is not available");
   }
   return loanService.applyForLoan(nid, amount);
}

Adding a timeout#

Real networks hang. I do not want a request to wait forever. So I add a deadline of ten seconds to the scope:

try (var scope = StructuredTaskScope.open(new FailFirstJoiner(),
       configuration -> configuration.withTimeout(Duration.ofSeconds(10)))) {
   // fork, join, use results ...
}

If the time runs out, the scope is cancelled and the joiner's timeout() method is called.

For demonstration purposes, I return null from timeout(), but in a real implementation, we should throw a proper exception to clearly indicate that the operation has timed out.

Java versions: from preview to final#

I started with the Java 25 preview. The API changed a little in each preview. That is normal for preview features.

Java

JEP

What changed

28

JEP 543

Final. No API change from Java 27. Remove --enable-preview and recompile.

27

JEP 533

Seventh preview. ExecutionException replaces FailedException. Joiner gets a third type parameter. New open overload that takes configuration.

26

JEP 525

Sixth preview. onTimeout() callback. allSuccessfulOrThrow() returns a List<T>.

25

JEP 505

Fifth preview. New open() and Joiner API.

My examples builds on the Java 27 toolchain.

When to use it#

Use structured concurrency when:

  • A request needs several independent calls, then needs all of them (my loan example).

  • You want the fastest answer from several sources.

  • You want failures to cancel the other work by default.

Think twice when:

  • You need a task that lives longer than the method that started it, like a background job. A scope is not made for that.

  • You are doing a long, one-time job. A plain executor can still be the right tool.

Conclusion#

Plain threads are easy to start and easy to lose. When one task fails, its sibling can keep running with nobody waiting, and your logs and thread dumps can’t show who started it. That is the orphan thread problem, and it is why tracing gets hard.

Structured concurrency fixes this with one rule: child tasks live inside a scope and must finish before the scope closes. 

The API was a preview in Java 25, changed a little in Java 26 and 27, and will become final in Java 28 (planned for March 2027).

Found this useful? Share it with your peers:

More Blogs & Related Reads

Continue reading technical insights written by Exabyting engineers