AsyncKeyedLock 6.0.5-alpha
See the version list below for details.
dotnet add package AsyncKeyedLock --version 6.0.5-alpha
NuGet\Install-Package AsyncKeyedLock -Version 6.0.5-alpha
<PackageReference Include="AsyncKeyedLock" Version="6.0.5-alpha" />
paket add AsyncKeyedLock --version 6.0.5-alpha
#r "nuget: AsyncKeyedLock, 6.0.5-alpha"
// Install AsyncKeyedLock as a Cake Addin #addin nuget:?package=AsyncKeyedLock&version=6.0.5-alpha&prerelease // Install AsyncKeyedLock as a Cake Tool #tool nuget:?package=AsyncKeyedLock&version=6.0.5-alpha&prerelease
AsyncKeyedLock
An asynchronous .NET Standard 2.0 library that allows you to lock based on a key (keyed semaphores), limiting concurrent threads sharing the same key to a specified number.
For example, suppose you were processing financial transactions, but while working on one account you wouldn't want to concurrently process a transaction for the same account. Of course, you could just add a normal lock, but then you can only process one transaction at a time. If you're processing a transaction for account A, you may want to also be processing a separate transaction for account B. That's where AsyncKeyedLock comes in: it allows you to lock but only if the key matches.
Installation
The recommended means is to use NuGet, but you could also download the source code from here.
Usage
You need to start off with creating an instance of AsyncKeyedLocker
or AsyncKeyedLocker<T>
. The recommended way is to use the latter, which is faster and consumes less memory. The former uses object
and can be used to mix different types of objects.
Dependency injection
services.AddSingleton<AsyncKeyedLocker>();
or (recommended):
services.AddSingleton<AsyncKeyedLocker<string>>();
Variable instantiation
var asyncKeyedLocker = new AsyncKeyedLocker();
or (recommended):
var asyncKeyedLocker = new AsyncKeyedLocker<string>();
or if you would like to set the maximum number of requests for the semaphore that can be granted concurrently (set to 1 by default):
// using AsyncKeyedLockOptions
var asyncKeyedLocker1 = new AsyncKeyedLocker<string>(new AsyncKeyedLockOptions(maxCount: 2));
// using Action<AsyncKeyedLockOptions>
var asyncKeyedLocker2 = new AsyncKeyedLocker<string>(o => o.MaxCount = 2);
There are also AsyncKeyedLocker<TKey>() constructors which accept the parameters of ConcurrentDictionary, namely the concurrency level, the capacity and the IEqualityComparer<TKey> to use.
Pooling
Whenever a lock needs to be acquired for a key that is not currently being processed, an AsyncKeyedLockReleaser
object needs to exist for that key and added to a ConcurrentDictionary
. In order to reduce allocations having to create objects only to dispose of them shortly after, AsyncKeyedLock
allows for object pooling. Whenever a new key is needed, it is taken from the pool (rather than created from scratch). If the pool is empty, a new object is created. This means that the pool will not throttle or limit the number of keys being concurrently processed. Once a key is no longer in use, the AsyncKeyedLockReleaser
object is returned back to the pool, unless the pool is already full up.
Usage of the pool can lead to big performance gains, but it can also very easily lead to inferior performance. If the pool is too small, the benefit from using the pool might be outweighed by the extra overhead from the pool itself. If, on the other hand, the pool is too big, then that's a number of objects in memory for nothing, consuming memory.
It is recommended to run benchmarks and tests if you intend on using pooling to make sure that you choose an optimal pool size.
Setting the pool size can be done via the AsyncKeyedLockOptions
in one of the overloaded constructors, such as this:
// using AsyncKeyedLockOptions
var asyncKeyedLocker1 = new AsyncKeyedLocker<string>(new AsyncKeyedLockOptions(poolSize: 100));
// using Action<AsyncKeyedLockOptions>
var asyncKeyedLocker2 = new AsyncKeyedLocker<string>(o => o.PoolSize = 100);
You can also set the initial pool fill (by default this is set to the pool size):
// using AsyncKeyedLockOptions
var asyncKeyedLocker = new AsyncKeyedLocker<string>(new AsyncKeyedLockOptions(poolSize: 100, poolInitialFill: 50));
// using Action<AsyncKeyedLockOptions>
var asyncKeyedLocker = new AsyncKeyedLocker<string>(o =>
{
o.PoolSize = 100;
o.PoolInitialFill = 50;
});
Locking
// without cancellation token
using (await asyncKeyedLocker.LockAsync(myObject))
{
...
}
// with cancellation token
using (await asyncKeyedLocker.LockAsync(myObject, cancellationToken))
{
...
}
You can also use timeouts with overloaded methods to set the maximum time to wait, either in milliseconds or as a TimeSpan
.
In the case you need to use timeouts to instead give up if unable to obtain a lock by a certain amount of time, you can also use TryLockAsync
methods which will call a Func<Task>
or Action
if the timeout is not expired, whilst returning a boolean representing whether or not it waited successfully.
There are also synchronous Lock
and TryLock
methods available.
If you would like to see how many concurrent requests there are for a semaphore for a given key:
int myRemainingCount = asyncKeyedLocker.GetRemainingCount(myObject);
If you would like to see the number of remaining threads that can enter the lock for a given key:
int myCurrentCount = asyncKeyedLocker.GetCurrentCount(myObject);
If you would like to check whether any request is using a specific key:
bool isInUse = asyncKeyedLocker.IsInUse(myObject);
Credits
This library was originally inspired by Stephen Cleary's solution, but has gone through a lot of changes since.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 is compatible. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- System.Threading.Tasks.Extensions (>= 4.5.4)
-
net5.0
- No dependencies.
NuGet packages (41)
Showing the top 5 NuGet packages that depend on AsyncKeyedLock:
Package | Downloads |
---|---|
EasyCaching.Core
EasyCaching is a open source caching library that contains basic usages and some advanced usages of caching which can help us to handle caching more easier! |
|
Volo.Abp.DistributedLocking.Abstractions
Package Description |
|
EFCoreSecondLevelCacheInterceptor
Entity Framework Core Second Level Caching Library. |
|
N3O.Umbraco.Extensions
TODO |
|
ZhileTime.Hope.DistributedLocking.Abstractions
Package Description |
GitHub repositories (15)
Showing the top 5 popular GitHub repositories that depend on AsyncKeyedLock:
Repository | Stars |
---|---|
jellyfin/jellyfin
The Free Software Media System - Server Backend & API
|
|
abpframework/abp
Open-source web application framework for ASP.NET Core! Offers an opinionated architecture to build enterprise software solutions with best practices on top of the .NET. Provides the fundamental infrastructure, cross-cutting-concern implementations, startup templates, application modules, UI themes, tooling and documentation.
|
|
Tyrrrz/DiscordChatExporter
Exports Discord chat logs to a file
|
|
stefanprodan/AspNetCoreRateLimit
ASP.NET Core rate limiting middleware
|
|
microsoft/kiota
OpenAPI based HTTP Client code generator
|
Version | Downloads | Last updated | |
---|---|---|---|
7.1.4 | 45,626 | 11/22/2024 | |
7.1.4-preview | 86 | 11/22/2024 | |
7.1.3 | 38,048 | 11/10/2024 | |
7.0.2 | 72,850 | 10/13/2024 | |
7.0.1 | 216,712 | 8/20/2024 | |
7.0.0 | 98,579 | 7/21/2024 | |
7.0.0-rc3 | 129 | 7/20/2024 | |
7.0.0-rc2 | 126 | 7/20/2024 | |
7.0.0-rc1 | 159 | 6/29/2024 | |
7.0.0-beta | 127 | 6/29/2024 | |
7.0.0-alpha | 125 | 6/29/2024 | |
6.4.2 | 304,601 | 4/21/2024 | |
6.4.1 | 1,380 | 4/21/2024 | |
6.4.0 | 794 | 4/20/2024 | |
6.3.4 | 1,404,852 | 1/23/2024 | |
6.3.4-rc | 576 | 1/23/2024 | |
6.3.4-beta | 554 | 1/23/2024 | |
6.3.3 | 17,478 | 1/14/2024 | |
6.3.2 | 1,396 | 1/14/2024 | |
6.3.0 | 1,518 | 1/14/2024 | |
6.2.6 | 19,069 | 1/1/2024 | |
6.2.5 | 1,612 | 12/30/2023 | |
6.2.4 | 75,990 | 12/6/2023 | |
6.2.3 | 5,312 | 12/3/2023 | |
6.2.3-beta | 777 | 12/2/2023 | |
6.2.2 | 792,077 | 10/9/2023 | |
6.2.1 | 1,987,237 | 4/10/2023 | |
6.2.0 | 95,910 | 2/25/2023 | |
6.1.1 | 64,092 | 1/27/2023 | |
6.1.1-rc | 1,115 | 1/27/2023 | |
6.1.1-beta | 1,078 | 1/27/2023 | |
6.1.0 | 18,150 | 1/26/2023 | |
6.0.5 | 44,558 | 1/2/2023 | |
6.0.5-alpha | 1,092 | 12/30/2022 | |
6.0.4 | 2,737 | 12/30/2022 | |
6.0.4-rc6 | 1,078 | 12/30/2022 | |
6.0.4-rc5 | 1,112 | 12/30/2022 | |
6.0.4-rc3 | 1,080 | 12/30/2022 | |
6.0.4-rc | 1,045 | 12/29/2022 | |
6.0.4-beta | 1,099 | 12/29/2022 | |
6.0.4-alpha | 1,146 | 12/29/2022 | |
6.0.3 | 3,243 | 12/29/2022 | |
6.0.2 | 29,755 | 12/18/2022 | |
6.0.1 | 2,616 | 12/17/2022 | |
5.1.2 | 3,722 | 12/16/2022 | |
5.1.1 | 11,724 | 12/13/2022 | |
5.1.0 | 4,396 | 12/3/2022 | |
5.0.4 | 10,828 | 11/27/2022 | |
5.0.3 | 3,152 | 11/26/2022 | |
5.0.3-rc | 1,103 | 11/26/2022 | |
5.0.2-rc | 1,056 | 11/26/2022 | |
5.0.1 | 3,642 | 11/19/2022 | |
4.0.2 | 7,193 | 11/13/2022 | |
3.2.3 | 3,988 | 10/26/2022 | |
3.2.1 | 2,983 | 10/23/2022 | |
3.2.0 | 2,653 | 10/23/2022 | |
3.0.1 | 3,186 | 10/18/2022 | |
3.0.0 | 2,972 | 10/16/2022 | |
2.0.3 | 17,097 | 6/29/2022 | |
2.0.2 | 17,932 | 3/13/2022 | |
2.0.1 | 3,056 | 3/13/2022 | |
2.0.0 | 3,134 | 3/11/2022 | |
1.1.0 | 4,314 | 12/11/2021 | |
1.0.1 | 3,094 | 11/22/2021 | |
1.0.0 | 3,016 | 11/22/2021 |
Optimizations and fixing of more rare race conditions.