AsyncLock Class

A pooled async mutual exclusion lock for coordinating access to shared resources.

Namespace

CryptoHives.Foundation.Threading.Async.Pooled

Syntax

public sealed class AsyncLock : IResettable

Overview

AsyncLock provides async mutual exclusion, similar to SemaphoreSlim(1,1) but optimized for the common async locking pattern. It returns a small value-type releaser that implements IDisposable/IAsyncDisposable so the lock can be released with a using pattern. The implementation uses pooled IValueTaskSource instances to minimize allocations in high-throughput scenarios and a local reusable waiter to avoid allocations for the first queued waiter.

It guards one resource. When the thing being guarded is one of many — a row, an account, a tenant, a cache entry — use AsyncKeyedLock<TKey> instead of a lock per key or a dictionary of locks: it serializes callers per key while letting unrelated keys run fully in parallel.

Benefits

Zero-allocation fast path: When the lock is uncontended the operation completes synchronously without heap allocations.
Pooled Task Sources: Reuses IValueTaskSource<Releaser> instances from an object pool when waiters are queued.
ValueTask-Based: Returns ValueTask<Releaser> for minimal allocation when the lock is available.
RAII Pattern: Uses disposable lock handles for automatic release.
Cancellation Support (optimized): Supports CancellationToken for queued waiters; on .NET 6+ registration uses UnsafeRegister with a static delegate to reduce execution-context capture and per-registration overhead.
High Performance: Optimized for both uncontended and contended scenarios while keeping allocations low.

Constructor

public AsyncLock(
    IGetPooledManualResetValueTaskSource<Releaser>? pool = null)

Parameter	Description
`pool`	Optional custom pool for ValueTaskSource instances.

Note: Unlike other primitives in this library, AsyncLock always runs continuations asynchronously (hardcoded to true). This prevents potential deadlocks in common lock usage patterns.

Properties

Property	Type	Description
`IsTaken`	`bool`	Gets whether the lock is currently held by a caller or queued handoff.

Methods

LockAsync

public ValueTask<Releaser> LockAsync(CancellationToken cancellationToken = default)

Asynchronously acquires the lock. Returns a disposable that releases the lock when disposed.

Parameters:

cancellationToken - Optional cancellation token; only observed if the lock cannot be acquired immediately.

Returns: A ValueTask<Releaser> that completes when the lock is acquired. Dispose the result to release the lock.

Notes on allocations and cancellation:

The fast path (uncontended) completes synchronously and performs no heap allocations.
The implementation maintains a local waiter instance that serves the first queued waiter without allocating. Subsequent waiters use instances obtained from the configured object pool; if the pool is exhausted a new instance is allocated.
Passing a CancellationToken will register a callback when the waiter is queued. On .NET 6+ the code uses UnsafeRegister together with a static delegate and a small struct context to minimize capture and reduce allocation/ExecutionContext overhead. Even so, cancellation registrations and creating Task objects for pre-cancelled tokens may allocate; prefer avoiding cancellation tokens unless necessary for the scenario.

Throws:

OperationCanceledException - If the operation is canceled via the cancellation token.

LockAsync (timeout)

public ValueTask<Releaser> LockAsync(TimeSpan timeout, CancellationToken cancellationToken = default)

Asynchronously acquires the lock, or throws TimeoutException if the timeout elapses before the lock becomes available.

Parameters:

timeout — The maximum time to wait. Pass Timeout.InfiniteTimeSpan to wait indefinitely (delegates to LockAsync() without allocating a TimeProvider).

Returns: A ValueTask<Releaser> that completes when the lock is acquired. Dispose the result to release the lock.

Throws:

TimeoutException — If the timeout elapses before the lock can be acquired.
OperationCanceledException — If the operation is canceled via the cancellation token.
ArgumentOutOfRangeException — If timeout is negative and not equal to Timeout.InfiniteTimeSpan.

Allocation notes:

Scenario	TimeProvider allocated?
Lock immediately available	No
`Timeout.InfiniteTimeSpan`	No
`TimeSpan.Zero` and locked	No (immediate exception)
Finite positive timeout	Yes — one instance, disposed on await

Example:

try
{
    using (await _lock.LockAsync(TimeSpan.FromSeconds(2)))
    {
        await DoWorkAsync();
    }
}
catch (TimeoutException)
{
    // Could not acquire lock within 2 seconds
    HandleTimeout();
}

TryLock

public bool TryLock(out Releaser releaser)

Attempts to acquire the lock without waiting.

Parameters:

releaser — The releaser for the acquired lock, if the method returns true. Dispose it to release the lock. default (no associated lock) if the method returns false.

Returns: true if the lock was acquired immediately; false if it is currently held or awaited by someone else.

Synchronous and non-throwing by design: unlike LockAsync(TimeSpan.Zero), a failed attempt never allocates an exception or a faulted ValueTask<Releaser> — there is nothing to await in the first place. Use it on paths that shed work rather than queue it, where contention is an expected outcome instead of an exceptional one.

Do not dispose the releaser from a failed TryLock. It is default(Releaser) and represents no acquired lock. In DEBUG builds, disposing it throws InvalidOperationException to surface the mistake; release builds silently ignore it. Always check the return value first.

Example:

public void RefreshIfIdle()
{
    if (_lock.TryLock(out var releaser))
    {
        using (releaser)
        {
            RefreshCache();
        }
    }
    // Held by someone else — skip; the refresh happens on their release
}

Allocation Behavior

Immediate acquisitions are completely allocation-free using atomic operations. When the lock is contended, waiting without a timeout is allocation-free on .NET 6.0+ (using UnsafeRegister for cancellation), while older frameworks may allocate for cancellation registration. Specifying a finite timeout allocates a timer that is automatically disposed when the operation completes. Exception and task allocations occur only if a timeout actually elapses or cancellation is triggered; successful acquisitions are otherwise allocation-free. Pooled IValueTaskSource<Releaser> instances are reused to minimize allocation pressure across repeated lock operations.

public bool TryReset()

Implements IResettable to allow returning this instance to a DefaultObjectPool<AsyncLock>.

Behavior:

Attempts to acquire the internal spin lock. If the lock is already held by a concurrent operation, the method returns false immediately and the pool discards the instance.
If the lock is acquired but the logical lock is currently held (IsTaken == true) or waiters are queued, the method returns false — the instance is still in active use and must not be recycled.
Otherwise the local waiter is reset and the method returns true.

Thread Safety: TryReset() is safe to call concurrently with other operations. It will simply return false if the instance is in use.

Example:

// Using AsyncLock with an object pool
var pool = new DefaultObjectPool<AsyncLock>(
    new DefaultPooledObjectPolicy<AsyncLock>());

var lk = pool.Get();
try
{
    using (await lk.LockAsync(ct))
    {
        // critical section
    }
}
finally
{
    pool.Return(lk); // calls TryReset() internally
}

Thread Safety

Thread-safe. All public methods are thread-safe and can be called concurrently from multiple threads.

Performance Characteristics

Uncontended Lock: O(1), synchronous completion (no allocation)
Contended Lock: O(1) to enqueue waiter; waiter instances are reused from the object pool (allocation only if pool is exhausted)
Lock Release: O(1) to signal next waiter
Memory: Minimal allocations due to pooled task sources and local waiter reuse

Benchmark Results

The benchmarks compare various AsyncLock implementations:

PooledAsyncLock: The pooled implementation from this library
ProtoPromiseAsyncLock: The implementation from the Proto.Promises.Threading library
RefImplAsyncLock: The reference implementation from Stephen Toub's blog, which does not support cancellation tokens
NitoAsyncLock: The implementation from the Nito.AsyncEx library
NeoSmartAsyncLock: The implementation from the NeoSmart.AsyncLock library
AsyncNonKeyedLocker: An implementation from the AsyncKeyedLock.AsyncNonKeyedLocker library which uses SemaphoreSlim internally
SemaphoreSlim: The .NET built-in synchronization primitive
VS.Threading AsyncSemaphore: The Microsoft.VisualStudio.Threading semaphore used as a lock-compatible baseline
DotNextAsyncExclusiveLock (net10.0 only): The DotNext.Threading.AsyncExclusiveLock implementation, which has no disposable releaser - callers call Release() explicitly

Single Lock Benchmark

This benchmark measures the performance of acquiring and releasing a single lock in an uncontended scenario. In order to understand the impact of moving from a lock or Interlocked implementation to an async lock, the InterlockedIncrement, lock and .NET 9 Lock with EnterScope() are also measured with a integer increment as workload. The benchmark shows both throughput (operations per second) and allocations per operation. ProtoPromise is currently a strong uncontended competitor and can beat the pooled implementation on raw throughput, while the pooled implementation stays allocation-free and keeps the same API shape and cancellation behavior used throughout this library. VS.Threading is also included as a semaphore-based comparison point, but in the published uncontended results it trails both ProtoPromise and the pooled implementation. The new .NET 9 Lock primitive shows slighlty better performance than the well known lock on an object, but AsyncLock remains competitive due to the fast path implementation with Interlocked variable based state.

View live Single Lock benchmark results and trend history →

The synchronous baselines (lock/Monitor, .NET 9 Lock/Lock.EnterScope, SpinLock, and the Interlocked variants) are broken out into their own comparison table, since they're several orders of magnitude faster than any async option and would otherwise flatten the async comparison on a shared chart:

View live synchronous lock/Interlocked baseline results and trend history →

Multiple Concurrent Lock Benchmark

This benchmark measures performance under contention with multiple concurrent lock requests (iterations). The benchmark shows both throughput (operations per second) and allocations per operation. Zero iterations duplicates the uncontended scenario. It is noticable that all implementations except the pooled one and ProtoPromise require memory allocations on contention, as long as the ValueTask is not converted to Task. ProtoPromise is particularly competitive here and can outperform the pooled AsyncLock in several low- and mid-contention cases, especially when comparing pure throughput. The pooled implementation still distinguishes itself by combining allocation-free ValueTask usage with built-in cancellation support and predictable behavior when integrated with the rest of this library. VS.Threading is included as another real-world baseline, but its semaphore-based path is slower and allocates under contention in the published results.

View live Multiple Concurrent Lock benchmark results and trend history →

Benchmark Analysis

Key Findings:

Uncontended Performance: AsyncLock performs comparably to or better than SemaphoreSlim in uncontended scenarios due to the optimized fast path that avoids allocations entirely.
Memory Efficiency: The pooled IValueTaskSource approach significantly reduces allocations compared to TaskCompletionSource-based implementations. This is especially beneficial in high-throughput scenarios.
Contended Scenarios: Under contention, the local waiter optimization ensures the first queued waiter incurs no allocation, while subsequent waiters benefit from pool reuse. ProtoPromise can outperform the pooled implementation in several published throughput measurements, while SemaphoreSlim is also competitive in some cases but always at the cost of allocations.
ValueTask Advantage: Returning ValueTask<Releaser> instead of Task allows always allocation free completion.

When to Choose AsyncLock:

High-throughput scenarios where lock acquisition is frequent
Memory-sensitive applications where allocation pressure matters
Scenarios where locks are typically contended or allocation free cancellation support is needed

Best Practices

DO: Use the using pattern to ensure lock release and await the result directly

// Good: Minimal time holding lock
public async Task UpdateAsync(Data newData)
{
    // Prepare outside lock
    var processed = await PrepareDataAsync(newData);

    // using ensures lock is released
    using (await _lock.LockAsync())
    {
        _data = processed;
    }
}

DO: Keep critical sections short

// Good: Minimal time holding lock
using (await _lock.LockAsync())
{
    _data = processed;
}

DO: Prefer avoiding CancellationToken for hot-path locks

Cancellation registrations allocate a small control structure. For hot-path code, omit the token when possible, or perform an early cancellationToken.IsCancellationRequested check before calling LockAsync to avoid allocations from Task.FromCanceled.

DO: Configure a larger pool under high contention

If you expect many concurrent waiters, provide a custom object pool with a larger retention size so allocations are avoided when the pool can satisfy requests.

DO: Use `LockAsync(TimeSpan)` to bound wait time

try
{
    using (await _lock.LockAsync(TimeSpan.FromSeconds(5)))
    {
        _data = await FetchAsync();
    }
}
catch (TimeoutException)
{
    HandleTimeout();
}

DO: Use `TryLock` when a missed acquisition is acceptable

// Opportunistic work that can be skipped when the lock is busy
if (_lock.TryLock(out var releaser))
{
    using (releaser)
    {
        DoOptionalWork();
    }
}

TryLock never waits and never allocates. Prefer it over LockAsync(TimeSpan.Zero) whenever the call site does not otherwise need a ValueTask<Releaser> — the zero-timeout overload signals a miss by throwing TimeoutException, which allocates.

DON'T: Create new locks repeatedly

// Bad: Creating new lock each time
public async Task OperationAsync()
{
    var lock = new AsyncLock(); // Don't do this!
    Task.Run(async ()=> await Work(lock));
    Task.Run(async ()=> await Work(lock));
}

public async Task Work(AsyncLock lock)
{
    using (await lock.LockAsync())
    {
        // Work...
    }
}

DON'T: Hold the lock during long-running operations

// Bad: Holding lock during slow operation
using (await _lock.LockAsync())
{
    await SlowDatabaseQueryAsync(); // Don't hold lock!
}

DON'T: Nest locks (may deadlock)

// Bad: Risk of deadlock
using (await _lock1.LockAsync())
{
    using (await _lock2.LockAsync()) // Deadlock risk!
    {
        // Work...
    }
}

Table of Contents

AsyncLock Class

Namespace

Syntax

Overview

Benefits

Constructor

Properties

Methods

LockAsync

LockAsync (timeout)

TryLock

Allocation Behavior

Thread Safety

Performance Characteristics

Benchmark Results

Single Lock Benchmark

Multiple Concurrent Lock Benchmark

Benchmark Analysis

Best Practices

DO: Use the using pattern to ensure lock release and await the result directly

DO: Keep critical sections short

DO: Prefer avoiding CancellationToken for hot-path locks

DO: Configure a larger pool under high contention

DO: Use `LockAsync(TimeSpan)` to bound wait time

DO: Use `TryLock` when a missed acquisition is acceptable

DON'T: Create new locks repeatedly

DON'T: Hold the lock during long-running operations

DON'T: Nest locks (may deadlock)

See Also

Table of Contents

AsyncLock Class

Namespace

Syntax

Overview

Benefits

Constructor

Properties

Methods

LockAsync

LockAsync (timeout)

TryLock

Allocation Behavior

Thread Safety

Performance Characteristics

Benchmark Results

Single Lock Benchmark

Multiple Concurrent Lock Benchmark

Benchmark Analysis

Best Practices

DO: Use the using pattern to ensure lock release and await the result directly

DO: Keep critical sections short

DO: Prefer avoiding CancellationToken for hot-path locks

DO: Configure a larger pool under high contention

DO: Use LockAsync(TimeSpan) to bound wait time

DO: Use TryLock when a missed acquisition is acceptable

DON'T: Create new locks repeatedly

DON'T: Hold the lock during long-running operations

DON'T: Nest locks (may deadlock)

See Also

DO: Use `LockAsync(TimeSpan)` to bound wait time

DO: Use `TryLock` when a missed acquisition is acceptable