NLTechnologies.LockIt 2.1.0

🔒 LockIt

Lightweight, async, per-key locking for .NET. Serialize concurrent operations on the same key while allowing full parallelism across different keys.

Features

Installation

dotnet add package NLTechnologies.LockIt

Quick Start

Manual Instantiation

using NLTechnologies.LockIt; using Microsoft.Extensions.Logging;
using var loggerFactory = LoggerFactory.Create(b => b.AddConsole()); var logger = loggerFactory.CreateLogger<AsyncKeyedLocker<string>>();
await using var locker = new AsyncKeyedLocker<string>(logger);
await using (await locker.AcquireAsync("order-123")) 
{ 
    // Only one task can execute this block for "order-123" at a time. 
    // Other keys like "order-456" are NOT blocked. 
    await ProcessOrderAsync("order-123"); 
}

With Dependency Injection

Register all LockIt services in one call:

Program.cs ⇒ builder.Services.AddLockIt();

Then inject IAsyncKeyedLocker<TKey> where needed:

public class OrderService 
{ 
    private readonly IAsyncKeyedLocker<string> _locker;

    public OrderService(IAsyncKeyedLockerFactory lockerFactory)
    {
        _locker = lockerFactory.Create<string>();
    }

    public async Task HandleAsync(string orderId, CancellationToken ct)
    {
        await using (await _locker.AcquireAsync(orderId, cancellationToken: ct))
        {
            await ProcessOrderAsync(orderId);
        }
    }
}

Try-Pattern (Non-Throwing Timeout)

await using var result = await locker.TryAcquireAsync("key", TimeSpan.FromSeconds(5));

if (result.Acquired) 
{ 
    // critical section 
} 
else 
{ 
    // lock was not acquired within the timeout 
}

Configuration

Pass AsyncKeyedLockerOptions to customize behavior:

var options = new AsyncKeyedLockerOptions 
{     
    // how often cleanup runs 
    LockIdleCleanupInterval = TimeSpan.FromSeconds(60),  

    // idle time before removal 
    LockIdleCleanupThreshold = TimeSpan.FromSeconds(30),  
    
    // threshold for warnings 
    LongHeldLockThreshold  = TimeSpan.FromMinutes(1),   
    
    // max wait during disposal 
    DisposeDrainTimeout  = TimeSpan.FromSeconds(10) 
};

await using var locker = new AsyncKeyedLocker<string>(logger, options);

Options available:

API Reference

IAsyncKeyedLocker<TKey>

IAsyncKeyedLockerFactory

ServiceCollectionExtensions

Metrics (OpenTelemetry)

LockIt exposes metrics under the meter name NLTechnologies.LockIt:

Subscribe in your OpenTelemetry configuration:

builder.Services.AddOpenTelemetry().WithMetrics(m => m.AddMeter(LockItMetrics.MeterName));

Project Structure

LockIt/ 
├── src/ │   
         └── NLTechnologies.LockIt/ │       
                                    ├── AsyncKeyedLocker.cs │       
                                    ├── AsyncKeyedLockerFactory.cs │       
                                    ├── AsyncKeyedLockerOptions.cs │       
                                    ├── IAsyncKeyedLocker.cs │       
                                    ├── IAsyncKeyedLockerFactory.cs │       
                                    ├── LockItMetrics.cs │       
                                    ├── ServiceCollectionExtensions.cs │       
                                    └── TryAcquireResult.cs 
├── tests/ │
           └── NLTechnologies.LockIt.Tests/ 
├── .github/workflows/ci.yml 
├── .editorconfig 
├── CHANGELOG.md 
├── CONTRIBUTING.md 
├── Directory.Build.props 
├── LICENSE 
├── NLTechnologies.LockIt.slnx 
└── README.md

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

Licensed under the Apache License 2.0.

Copyright © 2026 Noctua Lumen Technologies.