TransmittableThreadLocal (TTL)

TransmittableThreadLocal (TTL) provides the ability to pass ThreadLocal values across thread pools and other execution components that reuse threads.

While the standard JDK InheritableThreadLocal handles value passing from a parent thread to a newly created child thread, it fails in pooled environments where threads are reused. TTL solves this by ensuring that the ThreadLocal value present when a task is submitted to a thread pool is correctly passed to the task's execution context.

Key features:

• Zero dependencies.
• Supports Java 6 to 21 (Note: v2.13+ requires Java 8; use v2.12.x for Java 6 support).
• Extremely lightweight (~1000 SLOC).

To ensure that Mapped Diagnostic Context (MDC) values are correctly passed to worker threads in thread pools (like Executors), use the log4j2-ttl-thread-context-map integration. This solves the issue where Log4j2's default ThreadLocal implementation fails to propagate context when threads are reused.

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>log4j2-ttl-thread-context-map</artifactId>
    <version>1.3.0</version>
</dependency>

To extend the TTL Agent using a Transformlet, you must provide two components:

1. An implementation class: A class that implements the Transformlet interface to define how classes or methods should be modified during transformation.
2. A configuration file: A file located at META-INF/ttl.agent.transformlets within your classpath. This file must contain the fully qualified name of your implementation class.

TTL Agent scans the classpath for this specific file and automatically enables the extensions, similar to how JDK's ServiceLoader works. Simply adding the JAR containing your implementation to the application's classpath will activate it.

To ensure TransmittableThreadLocal (TTL) values are passed through the Vert.x EventBus, use the following methods:

Decorate java.lang.Runnable

Use TtlRunnable to decorate a Runnable before passing it to the EventBus.

Decorate io.netty.util.concurrent.SingleThreadEventExecutor

TTL support for io.netty.util.concurrent.SingleThreadEventExecutor is provided via the NettySingleThreadEventExecutorTtlTransformlet implementation.

To propagate MDC context across threads when using Logback, use the logback-mdc-ttl library. This integration is suitable for production environments where thread-local context must persist through thread pool execution.

<dependency>
    <groupId>com.ofpay</groupId>
    <artifactId>logback-mdc-ttl</artifactId>
    <version>1.0.2</version>
</dependency>

You can perform throughput (TPS) and pressure testing to compare the performance of TransmittableThreadLocal against standard ThreadLocal. These tests involve concurrent threads continuously creating new instances without manual cleanup.

Use the following scripts to execute the tests:

• For ThreadLocal: Run tps-ThreadLocal.sh (uses test class CreateThreadLocalInstanceTps).
• For TransmittableThreadLocal: Run tps-TransmittableThreadLocal.sh (uses test class CreateTransmittableThreadLocalInstanceTps).

To ensure TransmittableThreadLocal (TTL) values are propagated through the Vert.x EventBus, use the following approaches:

Decorate java.lang.Runnable

Use TtlRunnable to wrap Runnable tasks that are passed through the EventBus.

Decorate io.netty.util.concurrent.SingleThreadEventExecutor

TTL support for io.netty.util.concurrent.SingleThreadEventExecutor is provided via the NettySingleThreadEventExecutorTtlTransformlet agent transformlet.

If you prefer using your own Maven installation, ensure you are using Maven 3.3.9+.

mvn install

Instead of wrapping every individual task, you can wrap the entire thread pool using the TtlExecutors utility class. This automatically handles context propagation for all tasks submitted to that executor.

Available methods in TtlExecutors:

• getTtlExecutor(Executor executor): Wraps an Executor.
• getTtlExecutorService(ExecutorService executorService): Wraps an ExecutorService.
• getTtlScheduledExecutorService(ScheduledExecutorService scheduledExecutorService): Wraps a ScheduledExecutorService.

ExecutorService executorService = ...
// Wrap the executor service once
executorService = TtlExecutors.getTtlExecutorService(executorService);

TransmittableThreadLocal<String> context = new TransmittableThreadLocal<>();
context.set("value-set-in-parent");

Runnable task = new RunnableTask();
// No manual wrapping of 'task' needed here
executorService.submit(task);