Basic support for Structured Concurrency for existing applications

[paulbakker]

This is related to but not the same as #108. Scoped Values are related to Structured Concurrency, but this discussion is about streamlining the use of Structured Concurrency without Scoped Values.

The Problem

Structured Concurrency is in the fifth preview in JDK 25 and is expected to go to it's final version without changes in the next release.
The simplest way to use the API is the following:

 try (var scope = StructuredTaskScope.open()) {
    var task1 = scope.fork(() -> restClient.get()... );
    var task2 = scope.fork(() -> restClient.get()...);

    scope.join();
    return task1.get() + task2.get();
}

In this example both forks use a restClient to make a HTTP call.
This code example is broken, because the forks won't have context propagated, so the RestClient won't have tracing, security, etc.

The out-of-the-box solution that doesn't work - Scoped Values

Structured Concurrency is designed to be used together with Scoped Values (final in JDK 25).
We would wrap the code above in a ScopedValue.where(...).run(() -> { ... block, where we have ScopedValues for tracing context, security context etc.

However, adopting ScopedValues will require changes in many places, both where the values are set, and where they are read.
Because you need an explicit ScopedValue instance for each scoped value, I don't think there's a way to integrate with Micrometer Context Propagation. However, this should be explored further as well.

Workaround without ScopedValues

The StructuredConcurrency API allows to specify a ThreadFactory when opening a task scope. This is a hook we can use to propagate context to the threads created. I've experimented with this in our internal Spring Boot Netflix codebase, and seems to be a good way to adopt Structured Concurrency without requiring Scoped Values.
This issue is to discuss how Micrometer Context Propagation can make this experience better/easier for most users.
In Spring Boot Netflix we have added the following API.

package com.netflix.springboot.concurrency;

import java.util.concurrent.StructuredTaskScope;

public class ContextAwareStructuredTaskScope {

	private final ContextAwareThreadFactory contextAwareThreadFactory;

	public ContextAwareStructuredTaskScope(ContextAwareThreadFactory contextAwareThreadFactory) {
		this.contextAwareThreadFactory = contextAwareThreadFactory;
	}

	public <T, R> StructuredTaskScope<T, R> open(StructuredTaskScope.Joiner<? super T, ? extends R> joiner) {
		return StructuredTaskScope.open(joiner,
				configuration -> configuration.withThreadFactory(contextAwareThreadFactory));
	}

	public <T> StructuredTaskScope<T, Void> open() {
		var joiner = StructuredTaskScope.Joiner.awaitAllSuccessfulOrThrow();
		return StructuredTaskScope.open(joiner,
				configuration -> configuration.withThreadFactory(contextAwareThreadFactory));
	}
}

package com.netflix.springboot.concurrency;

import io.micrometer.context.ContextSnapshotFactory;

import java.util.concurrent.ThreadFactory;

public class ContextAwareThreadFactory implements ThreadFactory {

	private final ContextSnapshotFactory contextSnapshotFactory;

	public ContextAwareThreadFactory(ContextSnapshotFactory contextSnapshotFactory) {
		this.contextSnapshotFactory = contextSnapshotFactory;
	}

	@Override
	public Thread newThread(Runnable r) {
		var contextSnapshot = contextSnapshotFactory.captureAll();
		var wrapped = contextSnapshot.wrap(r);
		return Thread.ofVirtual().unstarted(wrapped);
	}
}

A user can inject the ContextAwareStructuredTaskScope and use it as follows, context propagation will work.

 try (var scope = contextAwareStructuredTaskScope.open()) {
    scope.fork(() -> //context works here!)    

What needs to be done?

The code I shared above isn't difficult, but it requires more setup code than what most users should be concerned about.
Is there an API that could be added to Micrometer Context Propagation to streamline this further?
I discussed this with @jonatan-ivanov in person, and he suggested to start a discussion here.

[jonatan-ivanov]

My two cents:

According to JEP 525: Structured Concurrency is proposed to have its sixth preview in Java 26 (at the moment it's not assigned to Java 26 though). I think this means that the earliest GA release of Structured Concurrency might be in Java 27 (2026 September).

It seems that Scoped Values do not work with other concurrency components ("unstructured concurrency") so at the moment there's no non-preview/GA way to automatically inherit/rebind Scoped Values when switching threads and it's likely that this will hold at least till Java 27. See @shakuzen's sample that demonstrates this: https://github.com/shakuzen/scoped-values-sample.

I think using and configuring ThreadFactory in StructuredTaskScope is a bit unfortunate but it seems that this is our only option (?) right now.

I'm also thinking if we should provide helper methods to make ThreadLocals available as ScopedValues and vice versa, something as simple as:

// maybe with better method names
static <T> ScopedValue.Carrier copy(ThreadLocal<T> from, ScopedValue<T> to) {
    return ScopedValue.where(to, from.get());
}

static <T> ScopedValue.Carrier copy(ScopedValue.Carrier carrier, ThreadLocal<T> from, ScopedValue<T> to) {
    return carrier.where(to, from.get());
}

static <T> void copy(ScopedValue<T> from, ThreadLocal<T> to) {
    to.set(from.get());
}

So that if you already use ScopedValue in your code but the data is available in a ThreadLocal:

return copy(TL, SV).call(this::doSomethingScopedValueAware);

[jonatan-ivanov]

Oh also, if will depend on classes in Java 25+ (e.g.: StructuredTaskScope), we likely need to create a new module for that since the baseline of the project is Java 8. In Micrometer we already done something similar, e.g: micrometer-java21

[rstoyanchev]

As I understand it, the request is about basic support for structured concurrency, separate from scoped values support under #108. It means allowing an existing application to fork subtasks and rely on context from ThreadLocal's.

For this we could provide a dedicated ThreadFactory that uses a given or static ContextSnapshotFactory instance, allows delegation to another ThreadFactory, and applies itself to a StructuredTaskScope.Configuration function, etc.

Beyond this building block, we can consider something to wrap the opening of a StructuredTaskScope with more control over config, but it's something that may also fit in Spring Framework.

Creating a module with a current Java baseline for a start #490 is a good idea.