Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

InheritableThreadLocal — inheriting thread-local values

InheritableThreadLocal<T> passes an initial value from a parent thread to a newly created child thread. Inheritance occurs when the thread is created, not at start() or when a task is submitted to a pool.

Version: Java SE 21; repository runtime, production runtime not attested

Syntax

InheritableThreadLocal<T> context = new InheritableThreadLocal<>();
context.set(value);
T current = context.get();
context.remove();
// Optional override: protected T childValue(T parentValue)

InheritableThreadLocal<T> in java.lang extends ThreadLocal<T>. An ordinary ThreadLocal initializes its value independently for each thread; this subclass lets a child inherit the parent's value. get(), set(), and remove() operate on the current thread's value; without a set or inherited value, the default initial value is null.

The child's value is determined when the Thread object is created, not at start(). The overridable method protected T childValue(T parentValue) runs in the parent before the child starts. By default it returns its argument: for objects, that means the same reference, not a deep copy. A later set() in one thread does not change the other thread's binding, but a mutable object can be shared and require synchronization.

In Java SE 21, inheritInheritableThreadLocals(false) on Thread.Builder disables inheritance; the default is enabled. The inheritance timing implies an important limitation: an existing pool worker does not receive a fresh context for every task. Do not use this mechanism as automatic request-context propagation into a pool. Clean up values with remove() in finally; this removes only the current thread's value.

The example uses immutable String values: the parent changes its value after constructing the child but before start(). The child still reads at-creation, and its own set() does not replace the parent's value. join() ensures the child finishes before the parent line is printed.

Examples

public class Main {
    private static final InheritableThreadLocal<String> CONTEXT =
            new InheritableThreadLocal<>();

    public static void main(String[] args) throws InterruptedException {
        CONTEXT.set("at-creation");
        try {
            Thread child = new Thread(() -> {
                try {
                    System.out.println("child: " + CONTEXT.get());
                    CONTEXT.set("child-only");
                } finally {
                    CONTEXT.remove();
                }
            });
            CONTEXT.set("after-creation");
            child.start();
            child.join();
            System.out.println("parent: " + CONTEXT.get());
        } finally {
            CONTEXT.remove();
        }
    }
}

Result

child: at-creation
parent: after-creation

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources