A concurrent map from green-thread IDs to values of type a.

Each thread may have at most one associated value. The table starts at an initial capacity (see newThreadStorageMap, newThreadStorageMapWith) and doubles automatically when full. Resize operations are serialized by an internal MVar lock so that at most one thread performs the expensive copy-and-swap at a time; other threads that discover a full table block on the lock and retry after the resize completes.

All read paths and ref-based hot-path operations are entirely lock-free. The MVar is only contended during table growth, which happens O(log n) times over the life of the map.

Create a ThreadStorageMap with a default initial capacity derived from the number of runtime capabilities: max 128 (capabilities * 32), rounded up to the next power of two.

The table resizes automatically when full, so this is a good default for most applications.

Create a ThreadStorageMap with at least the given number of initial slots.

The actual capacity is rounded up to the next power of two (minimum 16). The table doubles automatically when it runs out of slots. A load factor below 0.7 keeps probe chains short; resizing also cleans tombstones.

Retrieve the value associated with the current thread, if any.

Uses the fused CMM probe which reads CurrentTSO.id, applies the multiplicative hash, and linearly probes the key array in a single CMM call. Returns Nothing for both absent and detached entries without touching the value array in the detached case.

Retrieve the value associated with a specific thread.

Associate a value with the current thread, replacing any previous value.

Returns the previous value, or Nothing if the thread had no entry. A GC finalizer is registered on the first call per thread so that the entry is automatically cleaned up when the thread dies.

On the hot path (value already attached), no ThreadId is allocated and no FFI call is made. myThreadId is only called on the cold first-insert path to register the GC finalizer.

Like attach, but targets a specific thread.

Remove the value associated with the current thread.

Returns the removed value, or Nothing if the thread had no entry. The slot key is marked with the detached bit (a single atomic write to unboxed memory with no GC write barrier) so it can be reused by a future attach without registering a duplicate GC finalizer.

Like detach, but targets a specific thread.

Atomically read and update the value for the current thread.

The callback receives the current value (or Nothing) and returns a pair of the new value to store (or Nothing to remove the entry) and an arbitrary result.

Uses the fused CMM probe (stg_probeThreadSlot#). The probe reports attached/detached/absent via its return encoding, so the hot path (attached, updating the value) never checks the detached state at all.

-- Increment a counter, inserting 1 if absent:
update tsm (\old -> (Just (maybe 1 (+1) old), ()))

Like update, but targets a specific thread.

This is the most general function in the high-level API. attachOnThread and detachFromThread are implemented in terms of this.

Modify the value for the current thread in place if one is attached.

Does nothing if the thread has no entry or the entry is detached. The modification is strict (modifyIORef'). Uses the fused CMM probe.

Like adjust, but targets a specific thread.

Extract the numeric thread ID from an existing ThreadId.

This makes a cheap FFI call to rts_getThreadId. When you already hold a ThreadId and need its numeric form for lookupRaw or updateRaw, use this. Otherwise prefer getCurrentThreadId.

Read the current green thread's numeric ID directly from CurrentTSO.

This is implemented as a CMM primop, so no ThreadId box is allocated and no FFI call is made. Prefer this over getThreadId =<< myThreadId whenever you do not need the ThreadId value itself.

Retrieve a value using a pre-computed thread ID (from getThreadId).

Avoids the FFI call to rts_getThreadId that lookupOnThread would make internally. Uses a CMM primop for the key-array probe.

Generalized update using a pre-computed thread ID.

Behaves like updateOnThread but skips the internal getThreadId call. The ThreadId argument is still needed so a GC finalizer can be registered when a new entry is created. Uses a CMM primop for the key-array probe.

Get or create the IORef for a given thread.

If the thread already has an entry, returns its IORef (read-only probe, no CAS). Otherwise, creates a new IORef initialised to def, claims a slot via CAS, and registers a GC finalizer for cleanup.

The Int argument is the numeric thread ID (e.g. from getCurrentThreadId or fromIntegral . getThreadId).

Fused CMM fast path: get or create the IORef for the current thread.

Returns (threadId, ref).

Steady state (entry exists): read the table IORef, then a single CMM call reads CurrentTSO.id and linearly probes the key array, then one readArray# fetches the IORef. No ThreadId allocation, no FFI, no Maybe wrapper.

First call per thread: falls back to myThreadId, CAS-inserts a new IORef initialised to def, and registers a finalizer.

Look up the IORef for a thread by its numeric ID (Haskell-side probe).

Use this when you already have the numeric ID but not necessarily the current thread's TSO (e.g. inspecting another thread's slot).

Look up the IORef for the current thread using the fused CMM probe.

Returns (threadId, Maybe (IORef a)). The numeric thread ID is returned so you can pass it to ensureRef on the slow path without a second FFI call:

(tid, mref) <- lookupRefFast tsm
ref <- case mref of
  Just r  -> pure r
  Nothing -> do
    t <- myThreadId
    ensureRef tsm t tid defaultValue

Read the value from a per-thread IORef.

Thin wrapper around readIORef; provided for API symmetry with writeRef and modifyRef.

Write a value into a per-thread IORef.

Strictly modify the value in a per-thread IORef.

Equivalent to modifyIORef'.

Snapshot all live entries as (threadId, value) pairs.

Intended for monitoring and debugging, e.g. verifying that entries are cleaned up after threads exit. The result is a point-in-time snapshot; concurrent mutations may or may not be reflected.

Tombstone slots belonging to threads that are no longer alive, and shrink the table if the load factor drops below 25%.

Normally, slots are cleaned up by GC finalizers attached to the owning ThreadId. This function provides an eager alternative: it calls listThreads to obtain the set of live threads and tombstones any slot whose key is not in that set.

Internally builds a flat array of live thread IDs and passes it to a C function that qsorts it, then batch-scans the key array using SIMD (NEON / SSE2) linear search for small live sets or branchless binary search (Khuong / Lemire CMOV style) for large ones. A single unsafe ccall amortises FFI overhead across the full table scan. Tombstoning (key + value slot) is done on the Haskell side to maintain GC write barriers.

After tombstoning, if the number of remaining live entries is less than 1/4 of the table capacity (and the capacity exceeds the 16-slot minimum), the table is rehashed to a smaller power-of-two size under the resize MVar lock. This prevents unbounded memory use after bursts of short-lived threads.

This is a best-effort operation: if a resize occurs concurrently, some dead entries may survive in the new table until the next purge or GC.

@since base 4.18.0 (GHC 9.6)