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 value from the thread of submitting task to the thread of executing task.

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 so as 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:

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	TransmittableThreadLocal.Transmitter transmit all TransmittableThreadLocal and registered ThreadLocal(registered by TransmittableThreadLocal.Transmitter.registerThreadLocal(java.lang.ThreadLocal<T>, com.alibaba.ttl.TtlCopier<T>)) values of the current thread to other thread by static methods TransmittableThreadLocal.Transmitter.capture() => TransmittableThreadLocal.Transmitter.replay(Object) => TransmittableThreadLocal.Transmitter.restore(Object) (aka CRR operation).

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()	see ThreadLocal.get()
void	remove()	see ThreadLocal.remove()
void	set(T value)	see ThreadLocal.set(T)

Methods inherited from class java.lang.InheritableThreadLocal

childValue

Methods inherited from class java.lang.ThreadLocal

initialValue, withInitial

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

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()

see ThreadLocal.get()

Overrides:

get in class ThreadLocal<T>

set

public final void set(T value)

see ThreadLocal.set(T)

Overrides:

set in class ThreadLocal<T>

remove

public final void remove()

see ThreadLocal.remove()

Overrides:

remove in class ThreadLocal<T>