# Dotnext Concurrency

> Concurrent data structures and allocation-free async building blocks from the DotNext.Threading NuGet package - AsyncLazy, TaskCompletionPipe, reusable ValueTaskCompletionSource, CancellationTokenMultiplexer, AsyncCounter (throttling), AsyncStateTracker, distributed leases, BoundedObjectPool and the SIEVE-based RandomAccessCache (managed and unmanaged-memory variants). Use when replacing Lazy<T> or Lazy<Task<T>> with async initialization; when reducing allocations of TaskCompletionSource, linked CancellationTokenSource or Task.WhenEach in hot paths; when implementing rate limiting, change notification streams, an object pool, an LRU/concurrent cache (including a large cache that puts pressure on GC), or a distributed lease.

- Skill: `dotnet/dotnext-concurrency` (Agent Skill)
- Install (CLI): `npx get-skill add dotnet/dotnext-concurrency`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dotnet/dotnext-concurrency/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: .NET (Microsoft) (https://skillmd.com/u/dotnet)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/dotnet/dotnext-concurrency

---


# Before you start

1. Check which version of `DotNext.Threading` the project references (`.csproj` or
   `Directory.Packages.props`). This skill describes 6.x. For older versions, verify each
   member you use against the XML docs/IntelliSense of the referenced version.
2. The types below are in several namespaces. Each type is given either with its namespace
   (e.g. `DotNext.Threading.AsyncLazy<T>`) or with the namespace in parentheses next to it
   (e.g. `AsyncCounter` (`DotNext.Threading`)). Add the `using` for that namespace and use the short type name in code.
3. If this skill doesn't cover what you need (API details, more examples), find the relevant article
   in the documentation index: https://dotnet.github.io/dotNext/llms.txt

# Use Cases

- Consider `DotNext.Threading.AsyncLazy<T>` as async-friendly replacement of `System.Lazy<T>` class:
  - Failures are cached unless `resettable: true`, and the first caller's token cancels the computation for everyone
- Consider `DotNext.Threading.Tasks.TaskCompletionPipe<T>` as alternative to `Task.WhenEach` method call in the following cases
  - There is no way to supply a list of tasks to be awaited in the form of the list. Pipe supports adding new tasks dynamically via `Add` method
  - To reuse the same pipe between enumerations (which leads to reduced memory allocation) by calling `Reset` method
  - Ability to attach user data to every task to be tracked
- Consider `ValueTaskCompletionSource` or `ValueTaskCompletionSource<T>` (`DotNext.Threading.Tasks`) as alternative to `System.Threading.Tasks.TaskCompletionSource` or `System.Threading.Tasks.TaskCompletionSource<T>` classes in cases when the source can be reused between completions to reduce memory allocation
  -  Each `ValueTask` or `ValueTask<T>` it produces must be awaited exactly once and never after `Reset()`, or the consumer sees the next completion or an exception.
- Consider `DotNext.Threading.CancellationTokenMultiplexer` when multiple cancellation tokens need to be linked with each other and/or with the timeout in hot execution paths to replace memory allocation with pooling
- Consider `AsyncCounter` (`DotNext.Threading`) to organize rate limiting or throttling. Back-pressure is controlled by `HasConcurrencyLimit` and `ConcurrencyLevel` properties inherited from `QueuedSynchronizer` base class
- Consider `AsyncStateTracker` (`DotNext.Threading`) to track object changes asynchronously. It can be used to implement `System.Collections.Generic.IAsyncEnumerable<T>` interface to supply changed versions of the object. The producer calls `TryAdvance()` on each change and `TryComplete()` at the end. The consumer takes `CurrentState` and awaits `WaitNextAsync(state, token)`. That returns **false** once the tracker is completed. After it returns **true**, read the resource and take `CurrentState` again.
- Consider `LeaseConsumer` and `LeaseProvider<TMetadata>` (`DotNext.Threading.Leases`) abstract types for client-side and server-side distributed leases accordingly
  - `LeaseProvider<TMetadata>` needs `GetStateAsync` and `TryUpdateStateAsync` implemented over the shared storage (DB, blob, etc.).
  - `LeaseConsumer` needs `TryAcquireCoreAsync`, `TryRenewCoreAsync` and `ReleaseCoreAsync`, usually as calls to the provider.
- Object pooling can be organized with `DotNext.Collections.Concurrent.BoundedObjectPool<T>` instead of a custom pool implementation
  - `TryGet()` returns null when the pool is empty, so the caller creates the object itself.
  - `TryReturn()` returns false when the pool is full, so the caller must dispose or drop the object.
  - The capacity is rounded to a power of 2.
- Replace LRU cache with async-friendly SIEVE algorithm implementation exposed by `DotNext.Runtime.Caching.RandomAccessCache<TKey, TValue>` class
  - SIEVE has no contention over concurrent readers
  - SIEVE is not scan resistant: enumerating the cache doesn't update the recency of entries
  - It doesn't behave like dictionary. Instead, it exposes read or write session, which guarantee liveness of the cache entry during read or modification in case of concurrent eviction.
  - Use [this example](https://github.com/dotnet/dotNext/blob/master/src/examples/RandomAccessCacheBenchmark/Program.cs) to see how to consume its API.
- Consider `DotNext.Runtime.Caching.RandomAccessCache<TValue>` (where `TValue : unmanaged`) instead of `RandomAccessCache<TKey, TValue>` for large caches. It keeps the keys, the values and the SIEVE structures in unmanaged memory, so the cache size doesn't add GC mark work and GC pauses.
  - Prefer it when the cache holds a very large number of entries (hundreds of thousands to millions) and GC pauses or GC CPU time matter, the value is an unmanaged struct, and the key can be represented as bytes.
  - Prefer `RandomAccessCache<TKey, TValue>` when the value is or contains a reference type, the value must be updated in place, the cache must be enumerated, entries need weights or the cache must grow (`RandomAccessCache<TKey, TValue, TWeight>`), the key needs a custom `IEqualityComparer<TKey>`, or the cache is small enough that GC cost doesn't matter.
  - The key is a sequence of bytes copied to the entry. Wrap it with `RandomAccessCache.AsKey(ReadOnlyMemory<byte>)` or `RandomAccessCache.AsKey(string)` for `ChangeAsync`, `ReplaceAsync`, `TryRemoveAsync` and `InvalidateAsync`. These wrappers convert implicitly to `ReadOnlySpan<byte>` for `TryRead` and `Contains`, so use the same wrapper for reading and writing: `AsKey(string)` uses the UTF-16 bytes of the string, not UTF-8.
  - The value cannot be modified after insertion. Use `ReplaceAsync` to put a new value under the same key.
  - Capacity is fixed: there is no resize and no weights.
  - Use the `Eviction` callback to clean up after the removed value. It is called once per record, after all the sessions of the record are closed. The key passed to the callback is valid only during the call.
  - `MeasurementTags` sets the tags for its metrics (number of entries and allocated unmanaged memory).
  - Use [this benchmark](https://github.com/dotnet/dotNext/blob/master/src/DotNext.Benchmarks/Runtime/Caching/RandomAccessCacheReadBenchmark.cs) to see how to insert and read a record.
- Consider `ReferenceCounted<T>` and `ReferenceCountedOwner<T>` classes (`DotNext.Threading`) to replace handwritten reference counting mechanism
- Consider `DotNext.Threading.Atomic<T>` container type for synchronized access to the custom struct instead classic monitor lock. This type has no contention between concurrent readers, so multiple threads can read the value in parallel. But all writers are serialized.
  - It is a spin-based seqlock: readers retry while a write is in progress, and contended writers spin instead of blocking on a monitor. Use it for small structs and short updates, not for long critical sections.

# Pitfalls
- Every session of the unmanaged `RandomAccessCache<TValue>` (returned by `TryRead`, `ChangeAsync`, `ReplaceAsync`, `TryRemoveAsync` and their synchronous overloads) must be disposed. An undisposed session leaks the unmanaged memory of its entry, and an undisposed write session holds the bucket lock and blocks the disposal of the cache. Don't use `ReadSession.Value`, `ValueRef` or `Key` after disposing the session.
- Dispose the unmanaged `RandomAccessCache<TValue>` explicitly. The finalizer of an abandoned cache releases the memory, but it doesn't call the `Eviction` callback.
- The key wrapped by `RandomAccessCache.AsKey` must not change until the session is disposed, because the key is read twice: to find the bucket and to copy it to the entry.
- `Atomic<T>` is a mutable struct. Store it in a non-**readonly** field and access it by reference. A copy is an independent value with no synchronization with the original.
