NExtensions.Async

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: 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, and 8.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

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

📊 Benchmarks

BenchmarkDotNet v0.15.1, Windows 11 (10.0.26100.4770/24H2/2024Update/HudsonValley)
13th Gen Intel Core i9-13900KF 3.00GHz, 1 CPU, 32 logical and 24 physical cores
.NET SDK 8.0.411
  [Host]     : .NET 8.0.18 (8.0.1825.31117), X64 RyuJIT AVX2
  DefaultJob : .NET 8.0.18 (8.0.1825.31117), X64 RyuJIT AVX2

AsyncLock

AsyncReaderWriterLock

📄 License

This project is licensed under the MIT License.