net.openhft.chronicle.core.threads

Class CleaningThreadLocal<T>

java.lang.Object

java.lang.ThreadLocal<T>

net.openhft.chronicle.core.threads.CleaningThreadLocal<T>

Type Parameters:

T - the type stored in the thread-local variable

public class CleaningThreadLocal<T>
extends ThreadLocal<T>

CleaningThreadLocal - a ThreadLocal that never leaks native resources

CleaningThreadLocal augments ThreadLocal with two additional capabilities:

1. In-thread cleanup for CleaningThreads.
   A value attached to a CleaningThread is cleaned immediately (still on that same thread) when it is replaced or remove() is called.
2. Best-effort cleanup for ordinary threads.
   Values produced by threads that are not instances of CleaningThread are registered globally. The static method cleanupNonCleaningThreads() can be invoked-on a timer, in a background executor, or during JVM shutdown-to free resources that belong to threads which have already terminated.

This class is typically used for off-heap buffers, direct I/O handles, Closeables, or any resource that must be released deterministically even when user code forgets to call close().

Controlling orphan tracking

Orphan tracking can be toggled in two mutually-aware ways (highest precedence first):

1. System property
   Setting -Ddisable.ctl.orphan.tracking globally disables orphan tracking for every CleaningThreadLocal in the JVM, regardless of assertions or constructor flags. This is the easiest "set-and-forget" option for ultra-low-latency production deployments.
2. JVM assertions
   When above mechanisms is not used, orphan tracking is enabled only when assertions are turned on ( -ea ). This keeps the production fast path allocation-free by default.

Summary of common launch options:

   # production, no tracking
   java -Ddisable.ctl.orphan.tracking  ...

   # production, tracking ON for diagnostics
   java -ea:net.openhft.chronicle.core.threads.CleaningThreadLocal -cp ...

   # tests: assertions on, but tracking OFF for this one class
   java -ea -da:net.openhft.chronicle.core.threads.CleaningThreadLocal ...
 

See Also:

CleaningThread, cleanupNonCleaningThreads()

Method Summary

Modifier and Type	Method and Description
void	cleanup(T value) Idempotent helper that applies cleanup to value.
static void	cleanupNonCleaningThreads() Performs a single orphan-sweep: Iterates through all live CleaningThreadLocals that track non-CleaningThreads. Identifies threads that have terminated. Invokes the configured cleanup for each stale value. Purges the entry from internal bookkeeping.
T	get() Returns the value of this CleaningThreadLocal.
protected T	initialValue() Returns the initial value and records it for later cleanup when the thread is not a CleaningThread.
void	remove() Removes the value for this CleaningThreadLocal from the current thread and performs cleanup.
void	set(T value) Sets the value of this CleaningThreadLocal and performs cleanup if necessary.
String	toString()
static <T> CleaningThreadLocal<T>	withCleanup(Supplier<T> supplier, ThrowingConsumer<T,Exception> cleanup) Creates a CleaningThreadLocal with a supplier and a custom cleanup strategy.
static <T> CleaningThreadLocal<T>	withCleanup(Supplier<T> supplier, ThrowingConsumer<T,Exception> cleanup, Function<T,T> getWrapper) Creates a CleaningThreadLocal with a supplier, a custom cleanup strategy, and a function to apply when the get method is called.
static <T> CleaningThreadLocal<T>	withCleanup(ThrowingConsumer<T,Exception> cleanup) Creates a CleaningThreadLocal with a custom cleanup action but without an initial-value supplier.
static <T> CleaningThreadLocal<T>	withCloseQuietly(Supplier<T> supplier) Creates a CleaningThreadLocal whose cleanup simply calls Closeable.closeQuietly(java.lang.Object...).

Methods inherited from class java.lang.ThreadLocal

withInitial

Methods inherited from class java.lang.Object

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

Method Detail

withCloseQuietly

public static <T> CleaningThreadLocal<T> withCloseQuietly(Supplier<T> supplier)

Creates a CleaningThreadLocal whose cleanup simply calls Closeable.closeQuietly(java.lang.Object...).

Type Parameters:

T - any subtype of Closeable

Parameters:

supplier - supplies the resource (may return null)

Returns:

a new CleaningThreadLocal

withCleanup

public static <T> CleaningThreadLocal<T> withCleanup(ThrowingConsumer<T,Exception> cleanup)

Creates a CleaningThreadLocal with a custom cleanup action but without an initial-value supplier.

Parameters:

cleanup - The consumer that cleans up the resource.

Returns:

A CleaningThreadLocal instance.

withCleanup

public static <T> CleaningThreadLocal<T> withCleanup(Supplier<T> supplier,
                                                     ThrowingConsumer<T,Exception> cleanup)

Creates a CleaningThreadLocal with a supplier and a custom cleanup strategy.

Parameters:

supplier - The supplier that provides the resource.

cleanup - The consumer that cleans up the resource.

Returns:

A CleaningThreadLocal instance.

withCleanup

public static <T> CleaningThreadLocal<T> withCleanup(Supplier<T> supplier,
                                                     ThrowingConsumer<T,Exception> cleanup,
                                                     Function<T,T> getWrapper)

Creates a CleaningThreadLocal with a supplier, a custom cleanup strategy, and a function to apply when the get method is called.

Parameters:

supplier - The supplier that provides the resource.

cleanup - The consumer that cleans up the resource.

getWrapper - The function to apply when the get method is called.

Returns:

A CleaningThreadLocal instance.

cleanupNonCleaningThreads

public static void cleanupNonCleaningThreads()

Performs a single orphan-sweep:

1. Iterates through all live CleaningThreadLocals that track non-CleaningThreads.
2. Identifies threads that have terminated.
3. Invokes the configured cleanup for each stale value.
4. Purges the entry from internal bookkeeping.

Call at whatever cadence suits your application (e.g. every few seconds, once a minute, or only at JVM shutdown).

initialValue

protected T initialValue()

Returns the initial value and records it for later cleanup when the thread is not a CleaningThread.

Overrides:

initialValue in class ThreadLocal<T>

get

public T get()

Returns the value of this CleaningThreadLocal.

Overrides:

get in class ThreadLocal<T>

Returns:

The current value.

set

public void set(T value)

Sets the value of this CleaningThreadLocal and performs cleanup if necessary.

Overrides:

set in class ThreadLocal<T>

Parameters:

value - The new value to be set.

remove

public void remove()

Removes the value for this CleaningThreadLocal from the current thread and performs cleanup.

Overrides:

remove in class ThreadLocal<T>

cleanup

public void cleanup(@Nullable
                    T value)

Idempotent helper that applies cleanup to value. Any exception thrown by user code is swallowed and logged so that cleanup can never compromise the core invariant of this class.

toString

public String toString()

Overrides:

toString in class Object