How alibaba/transmittable-thread-local works
Project Type and Purpose
• This is an open-source library that provides “transmittable” ThreadLocal context for asynchronous execution. Its key purpose is to capture and propagate ThreadLocal values from when a task is submitted (for example, to a thread pool) to when it is executed.
• It handles both manual wrapping (via TtlRunnable, TtlCallable, and executor wrappers) and transparent enhancement using a Java Agent (instrumenting JDK ThreadPoolExecutor, ForkJoinTask, TimerTask, etc.).
File Structure
• The repository is organized into several Maven modules. Key top-level directories include:
• “ttl-core”: Holds the primary API implementation (e.g. TransmittableThreadLocal, wrapper classes, executor wrappers, SPI interfaces, and utility classes).
• “ttl-agent”: Contains the Java Agent implementation that transforms JDK classes at load time (for example, classes in the agent package and transformlet subpackages).
• “ttl-bom”: Provides a Maven bill of materials for dependency management.
• “ttl-integrations”: Includes sample integration projects (for agent extension transformlets and integrations for Vert.x 3/4).
• “ttl-kotlin”: The Kotlin adaptation of the library.
• “ttl2-compatible”: A module ensuring compatibility with TTL v2 interfaces.
• There are also various supporting files like Maven wrappers (mvnw, mvnw.cmd), GitHub workflow configurations, and documentation files (docs/ folder).
Architectural Patterns and Design Principles
• The design separates concerns. The cross-cutting concern of context propagation is encapsulated in the TTL API and its wrappers.
• The Java Agent module applies aspect-oriented principles by instrumenting JDK classes transparently.
• The modular Maven structure uses a multi-module design that decouples the core functionality from integrations and compatibility adaptations.
Putting It All Together
• Parallel to that, show a “Java Agent” block with sub-components (TtlAgent, TtlTransformer, individual transformlets) that intercept JDK thread pool classes.
• Sample/integration modules in a separate section that shows “Integration: Vert.x, Agent Extension Samples, etc.” interacting with both the core and the agent.