High-performance async synchronization primitives including AsyncReaderWriterLock, AsyncLazy, AsyncLock, AsyncAutoResetEvent, and AsyncManualResetEvent for modern .NET applications.
High-performance async synchronization primitives for modern .NET applications. This library provides efficient, allocation-friendly implementations of essential async coordination
types: AsyncReaderWriterLock, AsyncLock, and AsyncLazy.
Inspired from the awesome library of Stephen Cleary.
✨ Features
🔒 AsyncLock: Asynchronous mutual-exclusion lock
⚡ AsyncReaderWriterLock: Multiple concurrent readers or single exclusive writer
⏳ AsyncLazy<T>: Thread-safe asynchronous lazy initialization with multiple safety modes
Cancellation Support: Thorough CancellationToken support across all primitives
Zero dependencies: No external dependencies
Modern .NET: Supports .NET 6.0, 7.0, 8.0, and 9.0 with nullable reference types
Installation
dotnet add package NExtensions.Async
🚀 Quick Start
AsyncLock
An asynchronous mutual-exclusion lock that allows only one thread to enter the critical section at a time.
var asyncLock = new AsyncLock();
// Basic usage
using (await asyncLock.EnterScopeAsync())
{
// Only one thread at a time
await ProcessSharedResourceAsync();
}
// With cancellation
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
try
{
using (await asyncLock.EnterScopeAsync(cts.Token))
{
await LongRunningOperationAsync();
}
}
catch (OperationCanceledException)
{
// Handle timeout
}
// Allow synchronous continuations for better performance (use with care)
var fastLock = new AsyncLock(allowSynchronousContinuations: true);
AsyncReaderWriterLock
A reader-writer lock allowing multiple concurrent readers or a single exclusive writer.
var rwLock = new AsyncReaderWriterLock();
// Multiple readers can access simultaneously
using (await rwLock.EnterReaderScopeAsync())
{
var data = await ReadOnlyOperationAsync();
// Other readers can run concurrently
}
// Writers get exclusive access
using (await rwLock.EnterWriterScopeAsync())
{
await ModifyDataAsync();
// No other readers or writers allowed
}
// Configure synchronous continuations independently
var customRwLock = new AsyncReaderWriterLock(
allowSynchronousReaderContinuations: true,
allowSynchronousWriterContinuations: false
);
AsyncLazy<T>
Thread-safe asynchronous lazy initialization with configurable safety modes.
// Basic lazy initialization
var lazy = new AsyncLazy<DatabaseConnection>(
async () => await ConnectToDatabaseAsync()
);
DatabaseConnection connection = await lazy;
DatabaseConnection sameConnection = await lazy; // Same instance, no re-initialization
// Consume with cancellation support
var lazyWithCancellation = new AsyncLazy<string>(
async (ct) => await DownloadDataAsync(ct)
);
string data = await lazyWithCancellation.GetAsync(cancellationToken);
// Configure safety modes
var retryableLazy = new AsyncLazy<string>(
async () => await UnreliableOperationAsync(),
LazyAsyncSafetyMode.ExecutionAndPublicationWithRetry
);
AsyncLazy Safety Modes
// No thread safety, no retry (fastest)
var noneMode = new AsyncLazy<string>(factory, LazyAsyncSafetyMode.None);
// No thread safety, but retry on failure
var noneWithRetry = new AsyncLazy<string>(factory, LazyAsyncSafetyMode.NoneWithRetry);
// Thread-safe publication, retry on failure
var publicationOnly = new AsyncLazy<string>(factory, LazyAsyncSafetyMode.PublicationOnly);
// Thread-safe execution and publication, cache exceptions (default-like behavior)
var executionAndPublication = new AsyncLazy<string>(factory, LazyAsyncSafetyMode.ExecutionAndPublication);
// Thread-safe execution and publication with retry (safest)
var safestMode = new AsyncLazy<string>(factory, LazyAsyncSafetyMode.ExecutionAndPublicationWithRetry);
🔧 Synchronous Continuations
Both AsyncReaderWriterLock, AsyncLock support synchronous continuations for improved performance. This feature is disabled by default, as asynchronous continuations are
considered the safer default. Enable it only with caution and after prior benchmarking.
// Can be faster, but be careful of reentrancy and stack diving
var fastLock = new AsyncLock(allowSynchronousContinuations: true);
// Fine-tune reader vs writer continuation behavior
var customRwLock = new AsyncReaderWriterLock(
allowSynchronousReaderContinuations: true, // Safe for read-only operations
allowSynchronousWriterContinuations: false // Writers might need async context
);
🎯 Notes
Always dispose releasers: Use using statements to ensure locks are released
Handle cancellation: Provide appropriate CancellationToken values for timeout scenarios
Choose safety modes wisely: Balance performance vs. safety based on your requirements
Be cautious with sync continuations: Only enable when you understand the implications
Debugging: All types include comprehensive debugging support
