What it is

TransmittableThreadLocal (TTL) is a small, zero-dependency Java library from Alibaba that provides an enhanced InheritableThreadLocal capable of transmitting values between threads even when those threads are pooled and reused. It lives in the Java ecosystem and targets framework and middleware developers who need reliable context propagation across asynchronous execution boundaries. The library is Apache-2.0 licensed, roughly 1000 SLOC, and supports Java 6 through 21.

The concrete problem it solves is a gap in the JDK. InheritableThreadLocal passes values from a parent thread to a child thread at creation time, but thread pools create threads once and reuse them, so the parent-child relationship no longer holds. What applications actually need is to carry the ThreadLocal value captured at task submission time through to task execution time. TTL extends InheritableThreadLocal and adds a transmitteeValue() hook to control exactly how that value is transferred, closing the gap for any code that runs on ExecutorService, ForkJoinPool, or TimerTask.

Key capabilities

• Provides TransmittableThreadLocal, which extends InheritableThreadLocal and transmits values across pooled threads.
• Offers wrappers for ExecutorService, ForkJoinPool, TimerTask, and their thread factories.
• Supports decorating Runnable and Callable tasks directly.
• Includes a Java Agent that decorates JDK thread pool implementation classes without code changes.
• Exposes a protected transmitteeValue() method for customizing how values pass from submission to execution.
• Ships with integration APIs for frameworks and middleware, alongside user-facing APIs.
• Runs with zero dependencies and supports Java 6 through 21.

Who uses it and how

• Distributed tracing systems and full-link stress testing, where a trace or tag identifier must follow a request across thread pool boundaries.
• Log collection systems that attach request context to log records emitted on worker threads.
• Request-level caches that need the same request scope visible inside asynchronous tasks.
• Application containers and upper-layer frameworks that pass information down to lower-layer SDKs running on pooled threads.

Getting started

The library is consumed as a Maven dependency, and the README documents simple usage, thread pool decoration, and Java Agent startup parameters. The stable release line is v2.x on the 2.x branch; this branch carries the in-development v3.

When to use it — and when not to

Use TTL when context must survive thread pool reuse and the alternative is manual propagation at every submission site. Note that transmitted reference objects

TransmittableThreadLocal<String> context = new TransmittableThreadLocal<>();

// =====================================================

// 在父线程中设置
context.set("value-set-in-parent");

// =====================================================

// 在子线程中可以读取，值是"value-set-in-parent"
String value = context.get();

T