1---2name: dotnext-concurrency3description: Concurrent data structures and allocation-free async building blocks from the4 DotNext.Threading NuGet package - AsyncLazy, TaskCompletionPipe, reusable5 ValueTaskCompletionSource, CancellationTokenMultiplexer, AsyncCounter (throttling),6 AsyncStateTracker, distributed leases, BoundedObjectPool and the SIEVE-based RandomAccessCache7 (managed and unmanaged-memory variants). Use when replacing Lazy<T> or Lazy<Task<T>> with async8 initialization; when reducing allocations of TaskCompletionSource, linked CancellationTokenSource9 or Task.WhenEach in hot paths; when implementing rate limiting, change notification streams, an10 object pool, an LRU/concurrent cache (including a large cache that puts pressure on GC), or a11 distributed lease.12license: MIT13metadata:14 source: https://skillmd.com/skills/dotnet/dotnext-concurrency15 dotnext-version: "6.x"16---1718# Before you start19201. Check which version of `DotNext.Threading` the project references (`.csproj` or21 `Directory.Packages.props`). This skill describes 6.x. For older versions, verify each22 member you use against the XML docs/IntelliSense of the referenced version.232. The types below are in several namespaces. Each type is given either with its namespace24 (e.g. `DotNext.Threading.AsyncLazy<T>`) or with the namespace in parentheses next to it25 (e.g. `AsyncCounter` (`DotNext.Threading`)). Add the `using` for that namespace and use the short type name in code.263. If this skill doesn't cover what you need (API details, more examples), find the relevant article27 in the documentation index: https://dotnet.github.io/dotNext/llms.txt2829# Use Cases3031- Consider `DotNext.Threading.AsyncLazy<T>` as async-friendly replacement of `System.Lazy<T>` class:32 - Failures are cached unless `resettable: true`, and the first caller's token cancels the computation for everyone33- Consider `DotNext.Threading.Tasks.TaskCompletionPipe<T>` as alternative to `Task.WhenEach` method call in the following cases34 - 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` method35 - To reuse the same pipe between enumerations (which leads to reduced memory allocation) by calling `Reset` method36 - Ability to attach user data to every task to be tracked37- 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 allocation38 - 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.39- 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 pooling40- Consider `AsyncCounter` (`DotNext.Threading`) to organize rate limiting or throttling. Back-pressure is controlled by `HasConcurrencyLimit` and `ConcurrencyLevel` properties inherited from `QueuedSynchronizer` base class41- 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.42- Consider `LeaseConsumer` and `LeaseProvider<TMetadata>` (`DotNext.Threading.Leases`) abstract types for client-side and server-side distributed leases accordingly43 - `LeaseProvider<TMetadata>` needs `GetStateAsync` and `TryUpdateStateAsync` implemented over the shared storage (DB, blob, etc.).44 - `LeaseConsumer` needs `TryAcquireCoreAsync`, `TryRenewCoreAsync` and `ReleaseCoreAsync`, usually as calls to the provider.45- Object pooling can be organized with `DotNext.Collections.Concurrent.BoundedObjectPool<T>` instead of a custom pool implementation46 - `TryGet()` returns null when the pool is empty, so the caller creates the object itself.47 - `TryReturn()` returns false when the pool is full, so the caller must dispose or drop the object.48 - The capacity is rounded to a power of 2.49- Replace LRU cache with async-friendly SIEVE algorithm implementation exposed by `DotNext.Runtime.Caching.RandomAccessCache<TKey, TValue>` class50 - SIEVE has no contention over concurrent readers51 - SIEVE is not scan resistant: enumerating the cache doesn't update the recency of entries52 - 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.53 - Use [this example](https://github.com/dotnet/dotNext/blob/master/src/examples/RandomAccessCacheBenchmark/Program.cs) to see how to consume its API.54- 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.55 - 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.56 - 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.57 - 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.58 - The value cannot be modified after insertion. Use `ReplaceAsync` to put a new value under the same key.59 - Capacity is fixed: there is no resize and no weights.60 - 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.61 - `MeasurementTags` sets the tags for its metrics (number of entries and allocated unmanaged memory).62 - 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.63- Consider `ReferenceCounted<T>` and `ReferenceCountedOwner<T>` classes (`DotNext.Threading`) to replace handwritten reference counting mechanism64- 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.65 - 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.6667# Pitfalls68- 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.69- Dispose the unmanaged `RandomAccessCache<TValue>` explicitly. The finalizer of an abandoned cache releases the memory, but it doesn't call the `Eviction` callback.70- 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.71- `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.