[!IMPORTANT] This branch is TransmittableThreadLocal(TTL) v3, which is in development and has not been released yet.
See issue 432 for the v3 notes, work item list and its progress.

The stable version v2.x currently in use is on branch 2.x.

English Documentation |

• Functions
• Requirements
• User Guide
  • 1. Simple usage
  • 2. Transmit value even using thread pool
    • 2.1 Decorate Runnable and Callable
    • 2.2 Decorate thread pool
    • 2.3 Use Java Agent to decorate thread pool implementation class
• Java API Docs
• Maven Dependency
• How to compile and build
• More Documentation
• Related Resources
  • JDK Core Classes
• Who Used
• Contributors

Functions

TransmittableThreadLocal(TTL): The missing Java std lib(simple & 0-dependency) for framework/middleware, provide an enhanced InheritableThreadLocal that transmits values between threads even using thread pooling components. Support Java 6~21.

Class InheritableThreadLocal in JDK can transmit value to child thread from parent thread.

But when use thread pool, thread is cached up and used repeatedly. Transmitting value from parent thread to child thread has no meaning. Application need transmit value from the time task is created to the time task is executed.

If you have problem or question, please submit Issue or play fork and pull request dance.

[!NOTE] From TTL v2.13+ upgrade to Java 8.
If you need Java 6 support, use version 2.12.x

Requirements

The Requirements listed below is also why I sort out TransmittableThreadLocal in my work.

• Application container or high layer framework transmit information to low layer sdk.
• Transmit context to logging without application code aware.

User Guide

1. Simple usage

```java TransmittableThreadLocal context = new TransmittableThreadLocal<>();

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

// set in parent thread context.set("value-set-in-parent");

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

// read in child thread, value is "value-set-in-parent" String value = context.get(); ```

# See the executable demo SimpleDemo.kt with full source code.

This is the function of class InheritableThreadLocal, should use class InheritableThreadLocal instead.

But when use thread pool, thread is cached up and used repeatedly. Transmitting value from parent thread to child thread has no meaning. Application need transmit value from the time task is created to the point task is executed.

The solution is below usage.

2. Transmit value even using thread pool

2.1 Decorate Runnable and Callable

Decorate input Runnable and Callable by TtlRunnable and TtlCallable.

Sample code:

```java TransmittableThreadLocal context = new TransmittableThreadLocal<>();

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

// set in parent thread context.set("value-set-in-parent");

Runnable task = new RunnableTask(); // extra work, create decorated ttlRunnable object Runnable ttlRunnable = TtlRunnable.get(task); executorService.submit(ttlRunnable);

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

// read in task, value is "value-set-in-parent" String value = context.get(); ```

NOTE
Even when the same Runnable task is submitted to the thread pool multiple times, the decoration operations(ie TtlRunnable.get(task)) is required for each submission to capture the value of the TransmittableThreadLocal context at submission time; That is, if the same task is submitted next time without reperforming decoration and still using the last TtlRunnable, the submitted task will run in the context of the last captured context. The sample code is as follows:

```java // first submission Runnable task = new RunnableTask(); executorService.submit(TtlRunnable.get(task));

// ... some biz logic, // and modified TransmittableThreadLocal context ... context.set("value-modified-in-parent");

// next submission // reperform decoration to transmit the modified TransmittableThreadLocal context executorService.submit(TtlRunnable.get(task)); ```

Above code show how to dealing with Runnable, Callable is similar:

```java TransmittableThreadLocal context = new TransmittableThreadLocal<>();

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

// set in parent thread context.set("value-set-in-parent");

Callable call = new CallableTask(); // extra work, create decorated ttlCallable object Callable ttlCallable = TtlCallable.get(call); executorService.submit(ttlCallable);

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

// read in call, value is "value-set-in-parent" String value = context.get(); ```

# See the executable demo TtlWrapperDemo.kt with full source code.

2.2 Decorate thread pool

Eliminating the work of Runnable and Callable Decoration every time it is submitted to thread pool. This work can be completed in the thread pool.

Use util class TtlExecutors to decorate thread pool.

Util class TtlExecutors has below methods:

• getTtlExecutor: decorate interface Executor
• getTtlExecutorService: decorate interface ExecutorService
• getTtlScheduledExecutorService: decorate interface ScheduledExecutorService

Sample code:

```java ExecutorService executorService = ... // extra work, create decorated executorService object executorService = TtlExecutors.getTtlExecutorService(executorService);

TransmittableThreadLocal context = new TransmittableThreadLocal<>();

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

// set in parent thread context.set("value-set-in-parent");

Runnable task = new RunnableTask(); Callable call = new CallableTask(); executorService.submit(task); executorService.submit(call);

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

// read in Task or Callable, value is "value-set-in-parent" String value = context.get(); ```

# See the executable demo TtlExecutorWrapperDemo.kt with full source code.

2.3 Use Java Agent to decorate thread pool implementation class

In this usage, transmittance is transparent(no decoration operation).

Sample code:

```java // ## 1. upper layer logic of framework ## TransmittableThreadLocal context = new TransmittableThreadLocal<>(); context.set("value-set-in-parent");

// ## 2. biz logic ## ExecutorService executorService = Executors.newFixedThreadPool(3);

Runnable task = new RunnableTask(); Callable call = new CallableTask(); executorService.submit(task); executorService.submit(call);

// ## 3. underlayer logic of framework ## // read in Task or Callable, value is "value-set-in-parent" String value = context.get(); ```

# See the executable demo AgentDemo.kt with full source code, run demo by the script scripts/run-agent-demo.sh.

At present, TTL agent has decorated below JDK execution components(aka. thread pool) implementation:

• java.util.concurrent.ThreadPoolExecutor and java.util.concurrent.ScheduledThreadPoolExecutor
  • decoration implementation code is in JdkExecutorTtlTransformlet.java.
• java.util.concurrent.ForkJoinTaskcorresponding execution component is java.util.concurrent.ForkJoinPool
  • decoration implementation code is in ForkJoinTtlTransformlet.java, supports since version 2.5.1.
  • NOTE: CompletableFuture and (parallel) Stream introduced in Java 8 is executed through ForkJoinPool underneath, so after supporting ForkJoinPool, TTL also supports CompletableFuture and Stream transparently.
• java.util.TimerTaskcorresponding execution component is java.util.Timer
  • decoration implementation code is in TimerTaskTtlTransformlet.java, supports since version 2.7.0.
  • NOTE: Since version 2.11.2 decoration for TimerTask default is enable (because correctness is first concern, not the best practice like "It is not recommended to use TimerTask" :); before version 2.11.1 default is disable.
  • enabled/disable by agent argument ttl.agent.enable.timer.task:
    • -javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true
    • -javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false
  • more info about TTL agent arguments, see the javadoc of TtlAgent.java.

Add start options on Java command:

• -javaagent:path/to/transmittable-thread-local-2.x.y.jar

Java command example:

```bash java -javaagent:transmittable-thread-local-2.x.y.jar \ -cp classes \ com.alibaba.demo.ttl.agent.AgentDemo

if changed the TTL jar file name or the TTL version is before 2.6.0,

should set argument -Xbootclasspath explicitly.

java -javaagent:path/to/ttl-foo-name-changed.jar \ -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar \ -cp classes \ com.alibaba.demo.ttl.agent.AgentDemo

java -javaagent:path/to/transmittable-thread-local-2.5.1.jar \ -Xbootclasspath/a:path/to/transmittable-thread-local-2.5.1.jar \ -cp classes \ com.alibaba.demo.ttl.agent.AgentDemo ```

Run the script scripts/run-agent-demo.sh to start demo of "Use Java Agent to decorate thread pool implementation class".

NOTE

• Because TTL agent modified the JDK std lib classes, make code refer from std lib class to the TTL classes, so the TTL Agent jar must be added to boot classpath.
• Since v2.6.0, TTL agent jar will auto add self to boot classpath. But you should NOT modify the downloaded TTL jar file name in the maven repo(eg: transmittable-thread-local-2.x.y.jar).
  • if you modified the downloaded TTL jar file name(eg: ttl-foo-name-changed.jar), you must add TTL agent jar to boot classpath manually by java option -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar.

The implementation of auto adding self agent jar to boot classpath use the Boot-Class-Path property of manifest file(META-INF/MANIFEST.MF) in the TTL Java Agent Jar:

[!NOTE] Boot-Class-Path

A list of paths to be searched by the bootstrap class loader. Paths represent directories or libraries (commonly referred to as JAR or zip libraries on many platforms). These paths are searched by the bootstrap class loader after the platform specific mechanisms of locating a class have failed. Paths are searched in the order listed.

More info:

• Java Agent Specification - JavaDoc
• JAR File Specification - JAR Manifest
• Working with Manifest Files - The Java Tutorials

Java API Docs

The current version Java API documentation: https://alibaba.github.io/transmittable-thread-local/apidocs/

Maven Dependency

xml <dependency> <groupId>com.alibaba</groupId> <artifactId>transmittable-thread-local</artifactId> <version>2.14.4</version> </dependency>

Check available version at maven.org.

How to compile and build

Compilation/build environment require JDK 8+; Compilation can be performed in the normal way of Maven.

# The project already contains Maven that satisfied the required version, directly run mvnw in the project root directory; there is no need to manually install Maven by yourself.

```bash

Run test case

./mvnw test

Compile and package

./mvnw package

Run test case, compile and package, install TTL library to local Maven

./mvnw install

If you use maven installed by yourself, the version requirement: maven 3.3.9+

mvn install ```

More Documentation

• Developer Guide

Related Resources

JDK Core Classes

• WeakHashMap
• InheritableThreadLocal

Who Used

Some open-source projects used TTL:

• Middleware

  • sofastack/sofa-rpc
    SOFARPC is a high-performance, high-extensibility, production-level Java RPC framework
  • trpc-group/trpc-java
    A pluggable, high-performance RPC framework written in java
  • tencentmusic/supersonic
    SuperSonic is an out-of-the-box yet highly extensible framework for building ChatBI
  • dromara/hmily
    Distributed transaction solutions
  • dromara/gobrs-async
    
  • dromara/dynamic-tp
    Lightweight dynamic threadpool, with monitoring and alarming functions, base on popular config centers (already support NacosApolloZookeeper, can be customized through SPI)
  • opengoofy/hippo4j
    JDKTomcatJettyUndertow Apache RocketMQDubboRabbitMQHystrix
  • siaorg/sia-gateway
    microservice route gateway(zuul-plus)
  • huaweicloud/Sermant
    Sermant, a proxyless service mesh solution based on Javaagent
  • ZTO-Express/zms
    ZTO Message Service
  • lxchinesszz/tomato
    SpringBoot
  • ytyht226/taskflow
    (DAG)/
  • foldright/cffu
    Java CompletableFuture Fu, aka. CF-Fu, pronounced "Shifu"; include best practice/traps guide and a tiny sidekick library to improve user experience and reduce misuse.
  • tuya/connector
    The connector framework maps cloud APIs to local APIs based on simple configurations and flexible extension mechanisms

• Middleware/Data Processing

  • apache/shardingsphere
    Ecosystem to transform any database into a distributed database system, and enhance it with sharding, elastic scaling, encryption features & more
  • apache/kylin
    A unified and powerful OLAP platform for Hadoop and Cloud.
  • mybatis-flex/mybatis-flex
    mybatis-flex is an elegant Mybatis Enhancement Framework
  • basicai/xtreme1
    The Next GEN Platform for Multisensory Training Data. #3D annotation, lidar-camera annotation and image annotation tools are supported
  • oceanbase/odc
    An open-source, enterprise-grade database tool for collaborative development
  • sagframe/sagacity-sqltoy
    JavaORM
  • dromara/stream-query
    Mappermybatis-plus
  • luo-zhan/Transformer
    Transformer
  • SimonAlong/Neo
    OrmActiveRecordOrm
  • ppdaicorp/das
    (data access service)das consoledas clientdas server
  • didi/ALITA
    a layer-based data analysis tool
  • didi/daedalus
    

• Middleware/Flow engine

  • dromara/liteflow
    a lightweight and practical micro-process framework
  • alibaba/bulbasaur
    A pluggable, scalable process engine

• Middleware/Log

  • dromara/TLog
    Lightweight distributed log label tracking framework
  • fayechenlong/plumelog
    java
  • minbox-projects/minbox-logging
    AdminAdmin Ui
    • minbox-projects/api-boot
      SpringBootStarters
  • ofpay/logback-mdc-ttl
    logbacktransmittable-thread-localmdc
  • oldratlee/log4j2-ttl-thread-context-map
    Log4j2 TTL ThreadContextMap, Log4j2 extension integrated TransmittableThreadLocal to MDC

• Middleware/Bytecode

  • ymm-tech/easy-byte-coder
    Easy-byte-coder is a non-invasive bytecode injection framework based on JVM

• Business service or platform application

  • OpenBankProject/OBP-API
    An open source RESTful API platform for banks that supports Open Banking, XS2A and PSD2 through access to accounts, transactions, counterparties, payments, entitlements and metadata - plus a host of internal banking and management APIs
  • gz-yami/mall4j
    java uniapp
  • Joolun/JooLun-wx
    JooLun
  • HummerRisk/HummerRisk
    
  • XiaoMi/mone
Mone->->->->-
  • yangzongzhuan/RuoYi-Cloud
    Spring BootSpring Cloud & Alibaba
  • somowhere/albedo
    Spring Boot Spring SecurityMybatis RBAC
  • qwdigital/LinkWechat
    SCRM Java
  • fushengqian/fuint
    fuint
  • hiparker/opsli-boot
    
  • topiam/eiam
    EIAMEmployee Identity and Access Management ProgramIAM
  • Newspiral/newspiral-business
    

• Tool product

  • ssssssss-team/spider-flow
    
  • nekolr/slime
    
  • Jackson0714/PassJava-Platform
    Spring Cloud Java SpringBootSpring Cloud SpringBootMyBatisRedis MySql MongoDB RabbitMQElasticsearchDocker
  • martin-chips/DimpleBlog
SpringBoot2
  • zjcscut/octopus
    
  • xggz/mqr
    QQMQRmiraiAndroidQQweb

• Test solution or tool

  • alibaba/jvm-sandbox-repeater
    A Java server-side recording and playback solution based on JVM-Sandbox, /
  • vivo/MoonBox
    MoonboxJVM-Sandboxjvm-sandbox-repeaterjvm-sandbox-repeaterMoonbox
  • alibaba/testable-mock
    Mock
  • shulieTech/Takin
    measure online environmental performance test for full-links, Especially for microservices
    • shulieTech/LinkAgent
      a Java-based open-source agent designed to collect data and control Functions for Java applications through JVM bytecode, without modifying applications codes
  • alibaba/virtual-environment
    Route isolation with service sharing, Kubernetes

• Spring Cloud/Spring Boot microservices framework solution or scaffold

  • YunaiV/ruoyi-vue-pro
    Spring Boot + MyBatis Plus + Vue & Element + RBAC SaaS Activiti + Flowable
  • YunaiV/yudao-cloud
    RuoYi-Vue Cloud Spring Cloud Alibaba + MyBatis Plus + Vue & Element + RBAC
  • zlt2000/microservices-platform
    SpringBoot2.xSpringCloudSpringCloudAlibaba
  • dromara/lamp-cloud
    Jdk11 + SpringCloud + SpringBoot SaaS RBACXss
    • zuihou/lamp-util
      SpringBoot SpringCloud
  • matevip/matecloud
    Spring Cloud Alibaba
  • gavenwangcn/vole
    SpringCloud Micro service business framework
  • liuweijw/fw-cloud-framework
    springcloudoauth2SSOShardingdbcredisVue
  • liuht777/Taroco
    NacosSpring Cloud Alibabastarter OAuth2/
  • mingyang66/spring-parent
    RedisNettyAPI
  • budwk/budwk
BudWk NutzWk nutz nutzboot WebCMS
  • yinjihuan/spring-cloud
    Spring Cloud-Spring Cloud
    
  • louyanfeng25/ddd-demo
    DDDDemoDDD
  • nageoffer/12306
    12306

more open-source projects used TTL, see

Contributors

• Jerry Lee <oldratlee at gmail dot com> @oldratlee
• Yang Fang <snoop.fy at gmail dot com> @driventokill
• Zava Xu <zava.kid at gmail dot com> @zavakid
• wuwen <wuwen.55 at aliyun dot com> @wuwen5
• rybalkinsd <yan.brikl at gmail dot com> @rybalkinsd
• David Dai <351450944 at qq dot com> @LNAmp
• Your name here :-)