Why architecture matters here

ThreadLocal failures come from pool leaks. Architecture matters because pool reuse + missing remove combine into memory leaks.

Advertisement

The architecture: every piece explained

The top strip is basics. ThreadLocal<T>. Set / get / remove. Weak reference. Common use cases.

The middle row is risks. Leak in thread pools. InheritableThreadLocal. Virtual threads impact. ScopedValue alternative.

The lower rows are practice. Best practices. Metrics. Ops — code review + migration.

ThreadLocal — per-thread storage + lifecycle + leak risks + scoped valuescontext that doesn't leak between threadsThreadLocalstorage per threadSet / get / removeAPIWeak referenceGC eligibilityCommon use casescontext / user / traceLeak in thread poolsnot removedInheritableThreadLocalchild threadsVirtual threads impactmany threadsScopedValue alternativestructured contextBest practicesalways removeMetricsleak detectionOps — code review + audit + migrationavoidpropagateconsiderpreferenforcewatchwatchoperateoperate
ThreadLocal lifecycle + leak risks + ScopedValue alternative.
Advertisement

End-to-end flow

End-to-end: web handler sets ThreadLocal at request start; finally block removes at end. Pool worker reused; no leak. Virtual thread pattern prefers ScopedValue for context propagation with implicit cleanup.