CryptoHives.Foundation.Threading 0.7.37

🛡️ CryptoHives Open Source Initiative 🐝

An open, community-driven collection of cryptography and performance libraries for the .NET ecosystem, maintained by The Keepers of the CryptoHives.

🧵 CryptoHives.Foundation.Threading

Pooled async synchronization primitives for .NET, built to keep Task and TaskCompletionSource<T> allocations off the hot path.

🧱 Classes

Synchronization Primitives

Namespace: CryptoHives.Foundation.Threading.Async.Pooled

All primitives are backed by ObjectPool<T> and return ValueTask<T>, which keeps per-operation allocations out of high-throughput code paths.

Pooling Support Classes

Namespace: CryptoHives.Foundation.Threading.Pools

Note: This package no longer bundles CryptoHives.Foundation.Threading.Analyzers automatically. Install it separately if you want the Roslyn analyzers alongside the Threading library.

✨ Key Features

• Pooled primitives — synchronization objects backed by Microsoft.Extensions.ObjectPool
• ValueTask-based APIs — minimal to no allocations thanks to object pooling; pooled primitives retain a bounded number of objects, so allocation-free behaviour holds while the workload fits the pool (see Sizing the caches for AsyncKeyedLock<TKey>, the one primitive where the bound is worth sizing deliberately)
• CancellationToken support — full cancellation across all primitives, allocation-free on modern .NET
• ConfigureAwait support — works naturally with .ConfigureAwait(false) in library code
• Timeouts — every lock acquisition method accepts a timeout; a timed-out wait throws TimeoutException, a cancelled one throws OperationCanceledException
• Non-blocking attempts — AsyncLock.TryLock, AsyncKeyedLock.TryLock, AsyncSemaphore.TryWait, AsyncAutoResetEvent.TryWait, AsyncManualResetEvent.TryWait, AsyncCountdownEvent.TryWait, AsyncReaderWriterLock.TryReaderLock / TryUpgradeableReaderLock / TryWriterLock / Releaser.TryUpgradeToWriterLock, and AsyncExchange<T>.TryExchange all probe synchronously without allocating an exception or a ValueTask
• Configurable continuations — control whether continuations run synchronously or asynchronously
• Custom pools — supply your own IGetPooledManualResetValueTaskSource<T> (or ObjectPool<T>) for fine-grained control
• Drop-in replacement — swap the namespace, keep the same using-based patterns
• Optional analyzers — ValueTask misuse caught at compile time via the separate Threading.Analyzers package

📥 Installation

dotnet add package CryptoHives.Foundation.Threading

💡 Quick Examples

Mutual Exclusion — AsyncLock

using CryptoHives.Foundation.Threading.Async.Pooled;

private readonly AsyncLock _lock = new();

public async Task DoWorkAsync(CancellationToken ct)
{
    using (await _lock.LockAsync(ct).ConfigureAwait(false))
    {
        // Critical section — only one task at a time
        await ModifySharedStateAsync().ConfigureAwait(false);
    }
}

Per-Key Exclusion — AsyncKeyedLock<TKey>

private readonly AsyncKeyedLock<string> _locksByAccount = new();

public async Task TransferAsync(string accountId, CancellationToken ct)
{
    using (await _locksByAccount.LockAsync(accountId, ct).ConfigureAwait(false))
    {
        // Only one operation per accountId; other accounts proceed in parallel
        await ApplyTransferAsync(accountId).ConfigureAwait(false);
    }
}

Sizing the caches

AsyncKeyedLock<TKey> is allocation-free while a workload fits inside two caps, and degrades gracefully — not catastrophically — past either. Both default to 128.

A released key stays mapped as an idle entry rather than being torn down, so locking and releasing the same key repeatedly allocates nothing at all. That is what makes the common case free — and it is also why maxIdleEntries should span the hot key set rather than the total number of distinct keys ever seen. Retention is bounded by the keys actually used, so a generous cap costs a lock with few keys nothing.

Each entry supplies one waiter itself and the pool covers the rest, so a lock with 4 keys and 100 waiters behind each needs 396 pooled waiters — at the default, such a burst allocates on 268 of them.

// Sized to the workload: ~2000 hot tenants, up to ~500 waiters queued at peak
private readonly AsyncKeyedLock<string> _locksByTenant =
    new(maxIdleEntries: 2048, maxRetainedWaiters: 512);

Note: the default waiter pool is shared process-wide per closed TKey, so every AsyncKeyedLock<string> in the process draws on one budget. Passing maxRetainedWaiters is also what gives an instance a private pool.

Producer-Consumer — AsyncAutoResetEvent

private readonly AsyncAutoResetEvent _itemReady = new(initialState: false);
private readonly Queue<Item> _queue = new();

// Producer
public void Enqueue(Item item)
{
    _queue.Enqueue(item);
    _itemReady.Set(); // Releases exactly one waiter
}

// Consumer
public async Task<Item> DequeueAsync(CancellationToken ct)
{
    await _itemReady.WaitAsync(ct).ConfigureAwait(false);
    return _queue.Dequeue();
}

Broadcast — AsyncManualResetEvent

private readonly AsyncManualResetEvent _ready = new(set: false);

public async Task InitializeAsync()
{
    await LoadConfigurationAsync().ConfigureAwait(false);
    _ready.Set(); // All waiters are released at once
}

public async Task UseServiceAsync(CancellationToken ct)
{
    await _ready.WaitAsync(ct).ConfigureAwait(false);
    // Service is initialized
}

Bounded Concurrency — AsyncSemaphore

private readonly AsyncSemaphore _semaphore = new(initialCount: 4);

public async Task FetchAsync(CancellationToken ct)
{
    await _semaphore.WaitAsync(ct).ConfigureAwait(false);
    try
    {
        await CallExternalServiceAsync().ConfigureAwait(false);
    }
    finally
    {
        _semaphore.Release();
    }
}

Fan-Out/Fan-In — AsyncCountdownEvent

private readonly AsyncCountdownEvent _countdown = new(initialCount: 3);

// Each worker signals when its share of the work is done
public void WorkerCompleted() => _countdown.Signal();

// Coordinator waits until every worker has signalled
public async Task WaitForWorkersAsync(CancellationToken ct)
{
    await _countdown.WaitAsync(ct).ConfigureAwait(false);
    // All 3 workers completed
}

Multi-Phase Synchronization — AsyncBarrier

private readonly AsyncBarrier _barrier = new(participantCount: 3,
    postPhaseAction: b => Console.WriteLine($"Phase {b.CurrentPhase} completed by all participants"));

public async Task ParticipantWorkAsync(int participantId, CancellationToken ct)
{
    await DoPhase1WorkAsync(participantId).ConfigureAwait(false);

    // Blocks until every participant has arrived; the post-phase action then
    // runs once before all participants are released together
    await _barrier.SignalAndWaitAsync(ct).ConfigureAwait(false);

    await DoPhase2WorkAsync(participantId).ConfigureAwait(false);
}

Read-Write Separation — AsyncReaderWriterLock

private readonly AsyncReaderWriterLock _rwLock = new();

public async Task<Data> ReadAsync(CancellationToken ct)
{
    using (await _rwLock.ReaderLockAsync(ct).ConfigureAwait(false))
        return _cache.Get();
}

public async Task WriteAsync(Data data, CancellationToken ct)
{
    using (await _rwLock.WriterLockAsync(ct).ConfigureAwait(false))
        _cache.Set(data);
}

Wait-Until-Condition — AsyncConditionVariable

Pairs with an AsyncLock: a wait atomically releases the lock, suspends, and re-acquires it before returning — on every return path, including cancellation. Any number of callers can wait for a shared resource to reach a specific state; the condition is arbitrary state protected by the lock:

private readonly AsyncLock _lock = new();
private readonly AsyncConditionVariable _ready = new();
private ConnectionState _state = ConnectionState.Disconnected;

// The reconnect loop is the only writer of _state.
private async Task ReconnectLoopAsync(CancellationToken ct)
{
    while (!ct.IsCancellationRequested)
    {
        try
        {
            await ConnectAsync(ct).ConfigureAwait(false);

            using (await _lock.LockAsync(ct).ConfigureAwait(false))
            {
                _state = ConnectionState.Ready;
                _ready.SignalAll();   // every caller waiting for readiness wakes up
            }

            await RunUntilDisconnectedAsync(ct).ConfigureAwait(false);
        }
        finally
        {
            using (await _lock.LockAsync(CancellationToken.None).ConfigureAwait(false))
                _state = ConnectionState.Disconnected;
        }
    }
}

// Any caller can wait for the connection to become ready before using it.
public async Task<T> SendAsync<T>(Func<Task<T>> operation, CancellationToken ct)
{
    using (await _lock.LockAsync(ct).ConfigureAwait(false))
    {
        while (_state != ConnectionState.Ready)
            await _ready.WaitAsync(_lock, ct).ConfigureAwait(false);
    }

    return await operation().ConfigureAwait(false);   // outside the lock
}

Two-Party Rendezvous — AsyncExchange<T>

Two peer workers, doing the same job, meeting at the rendezvous every round to swap their current item for the other's — neither is a producer or a consumer, and nothing is ever buffered between rounds. This is the async counterpart of Java's Exchanger<V>, which the BCL has no equivalent of.

private readonly AsyncExchange<Item> _rendezvous = new();

public async Task RunPeerAsync(CancellationToken ct)
{
    Item mine = ComputeNextItem();

    while (!ct.IsCancellationRequested)
    {
        Item theirs = await _rendezvous.ExchangeAsync(mine, ct).ConfigureAwait(false);

        CrossCheck(mine, theirs);
        mine = ComputeNextItem();
    }
}

// Both peers run the exact same method - there is no asymmetric role to assign.
_ = Task.Run(() => RunPeerAsync(ct));
_ = Task.Run(() => RunPeerAsync(ct));

Non-Blocking Attempts — Try*

Every acquiring primitive exposes a synchronous Try* probe that returns false instead of throwing TimeoutException on a miss — no exception, no faulted ValueTask, nothing to await. Use them on paths that shed work rather than queue it.

// Opportunistic cache rebuild — skipped entirely if the lock is busy
if (_rwLock.TryWriterLock(out var releaser))
{
    using (releaser)
    {
        RebuildCache();
    }
}

// Rate limiter that reports "busy" instead of awaiting
if (_permits.TryWait())
{
    try { Handle(request); }
    finally { _permits.Release(); }
}
else
{
    Reject(request);
}

AsyncAutoResetEvent.TryWait() consumes the signal (like a completed WaitAsync()), whereas AsyncManualResetEvent.TryWait() and AsyncCountdownEvent.TryWait() are non-consuming aliases of IsSet. A failed releaser-returning Try* hands back default — never dispose it.

Custom Pool

using CryptoHives.Foundation.Threading.Pools;

var policy = new PooledValueTaskSourceObjectPolicy<bool>();
var pool   = new ValueTaskSourceObjectPool<bool>(policy, maximumRetained: 64);

var evt = new AsyncAutoResetEvent(
    initialState: false,
    runContinuationAsynchronously: true,
    pool: pool);

📋 ValueTask Contract

1. Await a ValueTask exactly once. A second await or AsTask() call may throw InvalidOperationException.
2. Avoid calling AsTask() before the primitive signals. With RunContinuationsAsynchronously=true (the default), storing the result of AsTask() too early causes a severe performance hit. Await the ValueTask directly wherever you can.
3. Always await or discard a waiter. If it's left unconsumed, the underlying IValueTaskSource never makes it back to the pool.

The separate Threading.Analyzers package enforces these rules at compile time.

📚 Documentation

🚨 Security Policy

If you discover a vulnerability, please don't open a public issue — follow the process on the CryptoHives Security Page instead.

⚖️ License

MIT — © 2026 The Keepers of the CryptoHives