Control tracking of non cleaning threads via system property fixes #273

[tgd]

Summary

This PR is a full refactor of CleaningThreadLocal that adds opt-in orphan-tracking, modernises the API, tightens safety contracts and expands the test-suite.

New functionality

• Global & per-instance orphan-tracking switches

  • -Ddisable.ctl.orphan.tracking → hard-off in prod
  • Assertions (-ea) → tracking on by default for debugging
  • New package-private ctor flag to force on/off in tests

• Static factory helpers

  • withCloseQuietly(...)
  • withCleanup(...)
  • withCleanup(..., Function<T,T> getWrapper)

• Lazy, best-effort orphan collection

  • cleanupNonCleaningThreads() now delegates to an internal doCleanup… helper and returns early when nothing is tracked.
  • Tracking map is created only when enabled, keeping the fast path allocation-free.

---

Implementation & API refinements

• Added DISABLE_CTL_ORPHAN_TRACKING constant and richer state fields (trackNonCleaningThreads, lazily-initialised nonCleaningThreadValues).
• Constructors now enforce non-null contracts via Objects.requireNonNull and annotate parameters/fields with JetBrains @NotNull/@Nullable.
• cleanup(T) is idempotent, swallows/logs user exceptions and is publicly exposed for clarity.
• Overhauled toString() for easier diagnostics.
• Internal cleanup loop rewritten for clearer intent and reduced contention.

Documentation & metadata

• Replaced brief comment with a detailed, task-oriented Javadoc (usage, tuning options, launch snippets).
• Updated copyright header to Chronicle Software 2016-2025.

Tests

• New CleaningThreadLocalOrphanPruningTest – parameterised test that proves the new tracking flag’s behaviour across 128 orphaned threads.
• CleaningThreadLocalTest updated to use the new factory methods and verify thread-safety/cleanup paths.

Compatibility notes

• No behavioural change when orphan tracking is disabled (the default in production).

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
81.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud