Package com.alibaba.ttl

Class TransmittableThreadLocal<T>

java.lang.Object

java.lang.ThreadLocal<T>

java.lang.InheritableThreadLocal<T>

com.alibaba.ttl.TransmittableThreadLocal<T>

All Implemented Interfaces:

TtlCopier<T>

public class TransmittableThreadLocal<T>
extends InheritableThreadLocal<T>
implements TtlCopier<T>

TransmittableThreadLocal(TTL) can transmit the value from the thread of submitting task to the thread of executing task even using thread pooling components.

Note:
TransmittableThreadLocal extends InheritableThreadLocal, so TransmittableThreadLocal first is a InheritableThreadLocal.
If the inheritable ability from InheritableThreadLocal has potential leaking problem, you can disable the inheritable ability:

❶ For thread pooling components(ThreadPoolExecutor, ForkJoinPool), Inheritable feature should never happen, since threads in thread pooling components is pre-created and pooled, these threads is neutral to biz logic/data.
Disable inheritable for thread pooling components by wrapping thread factories using methods getDisableInheritableThreadFactory / getDefaultDisableInheritableForkJoinWorkerThreadFactory.
Or you can turn on "disable inheritable for thread pool" by TtlAgent to wrap thread factories for thread pooling components automatically and transparently.

❷ In other cases, disable inheritable by overriding method InheritableThreadLocal.childValue(Object).
Whether the value should be inheritable or not can be controlled by the data owner, disable it carefully when data owner have a clear idea.

 TransmittableThreadLocal<String> transmittableThreadLocal = new TransmittableThreadLocal<>() {
     protected String childValue(String parentValue) {
         return initialValue();
     }
 }

More discussion about "disable the inheritable ability" see issue #100: disable Inheritable when it's not necessary and buggy.

Since:

0.10.0

Author:

Jerry Lee (oldratlee at gmail dot com), Yang Fang (snoop dot fy at gmail dot com)

See Also:

user guide docs and code repo of TransmittableThreadLocal(TTL), TtlRunnable, TtlCallable, TtlExecutors, TtlExecutors.getTtlExecutor(java.util.concurrent.Executor), TtlExecutors.getTtlExecutorService(java.util.concurrent.ExecutorService), TtlExecutors.getTtlScheduledExecutorService(java.util.concurrent.ScheduledExecutorService), TtlExecutors.getDefaultDisableInheritableThreadFactory(), TtlExecutors.getDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory), TtlForkJoinPoolHelper, TtlForkJoinPoolHelper.getDefaultDisableInheritableForkJoinWorkerThreadFactory(), TtlForkJoinPoolHelper.getDisableInheritableForkJoinWorkerThreadFactory(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory), TtlAgent

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TransmittableThreadLocal.Transmitter	Transmitter transmit all TransmittableThreadLocal and registered ThreadLocal values of the current thread to other thread.

Constructor Summary

Constructors

Constructor	Description
TransmittableThreadLocal()	Default constructor.
TransmittableThreadLocal(boolean disableIgnoreNullValueSemantics)	Constructor, create a TransmittableThreadLocal instance with parameter disableIgnoreNullValueSemantics to control "Ignore-Null-Value Semantics".

Method Summary

Modifier and Type	Method	Description
protected void	afterExecute()	Callback method after task object(TtlRunnable/TtlCallable) execute.
protected void	beforeExecute()	Callback method before task object(TtlRunnable/TtlCallable) execute.
T	copy(T parentValue)	Computes the value for this transmittable thread-local variable as a function of the source thread's value at the time the task Object is created.
T	get()
void	remove()
void	set(T value)
static <S> TransmittableThreadLocal<S>	withInitial(Supplier<? extends S> supplier)	Creates a transmittable thread local variable.
static <S> TransmittableThreadLocal<S>	withInitialAndCopier(Supplier<? extends S> supplier, TtlCopier<S> copierForChildValueAndCopy)	Creates a transmittable thread local variable.
static <S> TransmittableThreadLocal<S>	withInitialAndCopier(Supplier<? extends S> supplier, TtlCopier<S> copierForChildValue, TtlCopier<S> copierForCopy)	Creates a transmittable thread local variable.

Methods inherited from class java.lang.InheritableThreadLocal

childValue

Methods inherited from class java.lang.ThreadLocal

initialValue

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransmittableThreadLocal

public TransmittableThreadLocal()

Default constructor. Create a TransmittableThreadLocal instance with "Ignore-Null-Value Semantics".

About "Ignore-Null-Value Semantics":

1. If value is null(check by get() method), do NOT transmit this ThreadLocal.
2. If set null value, also remove value(invoke remove() method).

This is a pragmatic design decision:

1. use explicit value type rather than null value to express biz intent.
2. safer and more robust code(avoid NPE risk).

So it's strongly not recommended to use null value.

But the behavior of "Ignore-Null-Value Semantics" is NOT compatible with ThreadLocal and InheritableThreadLocal, you can disable this behavior/semantics via using constructor TransmittableThreadLocal(boolean) and setting parameter disableIgnoreNullValueSemantics to true.

More discussion about "Ignore-Null-Value Semantics" see Issue #157.

See Also:

TransmittableThreadLocal(boolean)

TransmittableThreadLocal

public TransmittableThreadLocal(boolean disableIgnoreNullValueSemantics)

Constructor, create a TransmittableThreadLocal instance with parameter disableIgnoreNullValueSemantics to control "Ignore-Null-Value Semantics".

Parameters:

disableIgnoreNullValueSemantics - disable "Ignore-Null-Value Semantics"

Since:

2.11.3

See Also:

TransmittableThreadLocal()

Method Detail

withInitial

@NonNull
public static <S> TransmittableThreadLocal<S> withInitial(@NonNull
                                                          Supplier<? extends S> supplier)

Creates a transmittable thread local variable. The initial value(ThreadLocal.initialValue()) of the variable is determined by invoking the get() method on the Supplier.

Type Parameters:

S - the type of the thread local's value

Parameters:

supplier - the supplier to be used to determine the initial value

Returns:

a new transmittable thread local variable

Throws:

NullPointerException - if the specified supplier is null

Since:

2.12.2

See Also:

withInitialAndCopier(Supplier, TtlCopier)

withInitialAndCopier

@NonNull
@ParametersAreNonnullByDefault
public static <S> TransmittableThreadLocal<S> withInitialAndCopier(Supplier<? extends S> supplier,
                                                                   TtlCopier<S> copierForChildValueAndCopy)

Creates a transmittable thread local variable. The initial value(ThreadLocal.initialValue()) of the variable is determined by invoking the get() method on the Supplier; and the child value(InheritableThreadLocal.childValue(Object)) and the transmitting value(copy(Object)) of the variable is determined by invoking the TtlCopier.copy(Object) method on the TtlCopier.

Type Parameters:

S - the type of the thread local's value

Parameters:

supplier - the supplier to be used to determine the initial value

copierForChildValueAndCopy - the ttl copier to be used to determine the child value and the transmitting value

Returns:

a new transmittable thread local variable

Throws:

NullPointerException - if the specified supplier or copier is null

Since:

2.12.3

See Also:

withInitial(Supplier)

withInitialAndCopier

@NonNull
@ParametersAreNonnullByDefault
public static <S> TransmittableThreadLocal<S> withInitialAndCopier(Supplier<? extends S> supplier,
                                                                   TtlCopier<S> copierForChildValue,
                                                                   TtlCopier<S> copierForCopy)

Creates a transmittable thread local variable. The initial value(ThreadLocal.initialValue()) of the variable is determined by invoking the get() method on the Supplier; and the child value(InheritableThreadLocal.childValue(Object)) and the transmitting value(copy(Object)) of the variable is determined by invoking the TtlCopier.copy(Object) method on the TtlCopier.

NOTE:
Recommend use withInitialAndCopier(Supplier, TtlCopier) instead of this method. In most cases, the logic of determining the child value(InheritableThreadLocal.childValue(Object)) and the transmitting value(copy(Object)) should be the same.

Type Parameters:

S - the type of the thread local's value

Parameters:

supplier - the supplier to be used to determine the initial value

copierForChildValue - the ttl copier to be used to determine the child value

copierForCopy - the ttl copier to be used to determine the transmitting value

Returns:

a new transmittable thread local variable

Throws:

NullPointerException - if the specified supplier or copier is null

Since:

2.12.3

See Also:

withInitial(Supplier), withInitialAndCopier(Supplier, TtlCopier)

copy

public T copy(T parentValue)

Computes the value for this transmittable thread-local variable as a function of the source thread's value at the time the task Object is created.

This method is called from TtlRunnable or TtlCallable when it create, before the task is started.

This method merely returns reference of its source thread value(the shadow copy), and should be overridden if a different behavior is desired.

Specified by:

copy in interface TtlCopier<T>

Since:

1.0.0

See Also:

TransmittableThreadLocal.Transmitter.registerThreadLocal(ThreadLocal, TtlCopier), TransmittableThreadLocal.Transmitter.registerThreadLocalWithShadowCopier(ThreadLocal), TransmittableThreadLocal.Transmitter.unregisterThreadLocal(java.lang.ThreadLocal<T>)

beforeExecute

protected void beforeExecute()

Callback method before task object(TtlRunnable/TtlCallable) execute.

Default behavior is to do nothing, and should be overridden if a different behavior is desired.

Do not throw any exception, just ignored.

Since:

1.2.0

afterExecute

protected void afterExecute()

Callback method after task object(TtlRunnable/TtlCallable) execute.

Default behavior is to do nothing, and should be overridden if a different behavior is desired.

Do not throw any exception, just ignored.

Since:

1.2.0

get

public final T get()

Overrides:

get in class ThreadLocal<T>

set

public final void set(T value)

Overrides:

set in class ThreadLocal<T>

remove

public final void remove()

Overrides:

remove in class ThreadLocal<T>