Padlock 1.1.0

<img src="https://github.com/jchristn/padlock/blob/main/assets/icon.png?raw=true" alt="Padlock" width="128px" height="128px" />

Padlock

Description

Padlock is a lightweight, high-performance library that provides key-based locking for multithreaded applications. It enables granular locking on specific resources identified by keys of any type, allowing for efficient concurrency control without unnecessary blocking.

Core features:

• Create locks based on any key type (string, int, GUID, custom objects, etc.)
• Support for both synchronous and asynchronous locking patterns
• Configurable concurrency per key (exclusive or shared locks)
• Runtime-adjustable concurrency via SetMaxCount (applied lazily; see below)
• Object pooling for reduced allocations under high throughput
• ValueTask-based async API for reduced overhead
• Efficient memory usage with automatic resource cleanup
• Cancellation support via standard CancellationToken
• Simple, intuitive API with IDisposable pattern for lock release

Special Thanks

Special thanks to @MarkCiliaVincenti for his help on this repo. His open source contributions have helped make this library better. He has a similar yet more robust and battle-tested library in AsyncKeyedLock which also offers striped locking, "lock-or-null" patterns, conditional locking, and more.

Constructor Parameters

Simple Example

using System;
using System.Threading;
using System.Threading.Tasks;
using Padlocks;

Padlock<string> padlock = new Padlock<string>(); // using string keys

using (padlock.Lock("resource1")) // synchronous
{
    Console.WriteLine("Resource 1 is locked and being accessed");
}

await Task.Run(async () => // asynchronous
{
    using (await padlock.LockAsync("resource2"))
    {
        Console.WriteLine("Resource 2 is locked and being accessed");
    }
});

CancellationTokenSource cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
try
{
    using (await padlock.LockAsync("resource3", cts.Token))
    {
        Console.WriteLine("Resource 3 is locked and being accessed");
    }
}
catch (OperationCanceledException)
{
    Console.WriteLine("Lock acquisition was cancelled");
}

bool isLocked = padlock.IsLocked("resource1");
Console.WriteLine($"Resource 1 is {(isLocked ? "locked" : "available")}");

Padlock supports mixing both synchronous and asynchronous lock operations on the same resource.

Configurable Concurrency

Use maxCount to allow multiple concurrent holders per key:

// Allow up to 3 concurrent holders per key
Padlock<string> padlock = new Padlock<string>(maxCount: 3);

// All three of these can proceed concurrently for the same key
Task task1 = Task.Run(async () =>
{
    using (await padlock.LockAsync("resource"))
    {
        // Work with resource concurrently (up to 3 at a time)
        await Task.Delay(1000);
    }
});

Task task2 = Task.Run(async () =>
{
    using (await padlock.LockAsync("resource"))
    {
        await Task.Delay(1000);
    }
});

Task task3 = Task.Run(async () =>
{
    using (await padlock.LockAsync("resource"))
    {
        await Task.Delay(1000);
    }
});

await Task.WhenAll(task1, task2, task3);

Adjusting Concurrency at Runtime

The instance-wide maxCount can be changed at any time with SetMaxCount, and the current value can be read from the MaxCount property:

Padlock<string> padlock = new Padlock<string>(maxCount: 1); // exclusive to start

padlock.SetMaxCount(4);            // allow up to 4 concurrent holders
int current = padlock.MaxCount;    // 4

The new limit is applied lazily:

• It takes effect for any key acquired after the call, and for any currently-idle key the next time it is acquired (including lock entries recycled from the internal pool).
• A key that is active at the moment of the call keeps its existing limit until every holder and waiter releases and its entry becomes idle. The next acquisition then adopts the new limit.

In practice this means an increase becomes visible as keys are acquired or recycled, while a decrease only takes effect for a given key once that key drains to zero holders at least once. Existing holders are never evicted, so a continuously-busy key that never drains will retain its previous limit until it does. SetMaxCount throws ArgumentOutOfRangeException if the value is less than 1.

Lock With Custom Types

Padlock works with any type that properly implements equality comparison:

// Custom type with custom equality logic
public class ResourceKey : IEquatable<ResourceKey>
{
    public string Name { get; }
    public int Id { get; }

    public ResourceKey(string name, int id)
    {
        Name = name;
        Id = id;
    }

    public bool Equals(ResourceKey other)
    {
        if (other is null) return false;
        return Name == other.Name && Id == other.Id;
    }

    public override bool Equals(object obj)
    {
        return obj is ResourceKey key && Equals(key);
    }

    public override int GetHashCode()
    {
        return HashCode.Combine(Name, Id);
    }
}

Padlock<ResourceKey> padlock = new Padlock<ResourceKey>();
ResourceKey resourceKey = new ResourceKey("UserProfile", 42);

using (padlock.Lock(resourceKey))
{
    Console.WriteLine("Resource is locked and being accessed");
}

Performance

Padlock is designed for high performance with minimal overhead:

• Uses SemaphoreSlim for efficient lock management
• Object pooling reduces allocations in high-throughput scenarios
• Monitor-based coordination for race-free cleanup
• Automatically cleans up unused lock objects to reduce memory usage
• Avoids unnecessary blocking when possible
• Handles high-contention scenarios gracefully

Installation

Install-Package Padlock

Or via the .NET CLI:

dotnet add package Padlock

Version History

Refer to CHANGELOG.md.

Icon

Many thanks to Vector Stall for creating the icon.