Class TransmittableThreadLocal<T>
- All Implemented Interfaces:
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 ClassesModifier and TypeClassDescriptionstatic class
Transmitter
transmit allTransmittableThreadLocal
and registeredThreadLocal
values of the current thread to other thread. -
Constructor Summary
ConstructorsConstructorDescriptionDefault constructor.TransmittableThreadLocal
(boolean disableIgnoreNullValueSemantics) Constructor, create aTransmittableThreadLocal
instance with parameterdisableIgnoreNullValueSemantics
to control "Ignore-Null-Value Semantics". -
Method Summary
Modifier and TypeMethodDescriptionprotected void
Callback method after task object(TtlRunnable
/TtlCallable
) execute.protected void
Callback method before task object(TtlRunnable
/TtlCallable
) execute.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.final T
get()
final void
remove()
final void
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
-
Constructor Details
-
TransmittableThreadLocal
public TransmittableThreadLocal()Default constructor. Create aTransmittableThreadLocal
instance with "Ignore-Null-Value Semantics".About "Ignore-Null-Value Semantics":
- If value is
null
(check byget()
method), do NOT transmit thisThreadLocal
. - If set
null
value, also remove value(invokeremove()
method).
This is a pragmatic design decision:
- use explicit value type rather than
null
value to express biz intent. - 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
andInheritableThreadLocal
, you can disable this behavior/semantics via using constructorTransmittableThreadLocal(boolean)
and setting parameterdisableIgnoreNullValueSemantics
totrue
.More discussion about "Ignore-Null-Value Semantics" see Issue #157.
- See Also:
- If value is
-
TransmittableThreadLocal
public TransmittableThreadLocal(boolean disableIgnoreNullValueSemantics) Constructor, create aTransmittableThreadLocal
instance with parameterdisableIgnoreNullValueSemantics
to control "Ignore-Null-Value Semantics".- Parameters:
disableIgnoreNullValueSemantics
- disable "Ignore-Null-Value Semantics"- Since:
- 2.11.3
- See Also:
-
-
Method Details
-
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 theget()
method on theSupplier
.- 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
@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 theget()
method on theSupplier
; and the child value(InheritableThreadLocal.childValue(Object)
) and the transmitting value(copy(Object)
) of the variable is determined by invoking theTtlCopier.copy(Object)
method on theTtlCopier
.- Type Parameters:
S
- the type of the thread local's value- Parameters:
supplier
- the supplier to be used to determine the initial valuecopierForChildValueAndCopy
- 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:
-
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 theget()
method on theSupplier
; and the child value(InheritableThreadLocal.childValue(Object)
) and the transmitting value(copy(Object)
) of the variable is determined by invoking theTtlCopier.copy(Object)
method on theTtlCopier
.NOTE:
Recommend usewithInitialAndCopier(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 valuecopierForChildValue
- the ttl copier to be used to determine the child valuecopierForCopy
- 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:
-
copy
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
orTtlCallable
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.
-
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
- Overrides:
get
in classThreadLocal<T>
-
set
- Overrides:
set
in classThreadLocal<T>
-
remove
public final void remove()- Overrides:
remove
in classThreadLocal<T>
-