NExtensions.Async 1.2.0

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, AsyncLazy, AsyncAutoResetEvent, and AsyncManualResetEvent. 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
• 🚥 AsyncAutoResetEvent: Signals a single waiting task and automatically resets
• 🚩 AsyncManualResetEvent: Signals all waiting tasks and remains signaled until manually reset
• 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);

AsyncAutoResetEvent

An asynchronous event that, when signaled, releases a single waiting task and then automatically resets to a non-signaled state.

// Initialize non-signaled
var autoEvent = new AsyncAutoResetEvent(initialState: false);

// Task 1: Wait for signal
await autoEvent.WaitAsync();

// Task 2: Signal the event
autoEvent.Set(); // Task 1 resumes, event is automatically reset

AsyncManualResetEvent

An asynchronous event that, when signaled, remains signaled until manually reset, allowing all current and future waiting tasks to proceed.

// Initialize non-signaled
var manualEvent = new AsyncManualResetEvent(initialState: false);

// Multiple tasks can wait
var task1 = manualEvent.WaitAsync();
var task2 = manualEvent.WaitAsync();

// Signal the event
manualEvent.Set(); // Both task1 and task2 resume

// Event remains signaled
await manualEvent.WaitAsync(); // Completes immediately

// Reset the event
manualEvent.Reset(); // Future WaitAsync() will block

🔧 Synchronous Continuations

AsyncReaderWriterLock, AsyncLock, AsyncAutoResetEvent, and AsyncManualResetEvent 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);
var fastEvent = new AsyncAutoResetEvent(initialState: false, 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

AsyncLazy

AsyncAutoResetEvent

AsyncManualResetEvent

📄 License

This project is licensed under the MIT License.