CloseableThreadLocal (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util, class: CloseableThreadLocal

Package org.apache.lucene.util

# Class CloseableThreadLocal<T>

java.lang.Object
org.apache.lucene.util.CloseableThreadLocal<T>

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public class CloseableThreadLocal<T> extends Object implements Closeable
Java's builtin ThreadLocal has a serious flaw: it can take an arbitrarily long amount of time to dereference the things you had stored in it, even once the ThreadLocal instance itself is no longer referenced. This is because there is single, master map stored for each thread, which all ThreadLocals share, and that master map only periodically purges "stale" entries.

While not technically a memory leak, because eventually the memory will be reclaimed, it can take a long time and you can easily hit OutOfMemoryError because from the GC's standpoint the stale entries are not reclaimable.

This class works around that, by only enrolling WeakReference values into the ThreadLocal, and separately holding a hard reference to each stored value. When you call `close()`, these hard references are cleared and then GC is freely able to reclaim space by objects stored in it.

We can not rely on `ThreadLocal.remove()` as it only removes the value for the caller thread, whereas `close()` takes care of all threads. You should not call `close()` until all threads are done using the instance.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CloseableThreadLocal()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  `T`
  `get()`
  `protected T`
  `initialValue()`
  `void`
  `set(T object)`

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### CloseableThreadLocal

    public CloseableThreadLocal()

- ## Method Details

  - ### initialValue

    protected T initialValue()

  - ### get

    public T get()

  - ### set

    public void set(T object)

  - ### close

    public void close()
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`