EonaCat.Lock 1.0.0

EonaCat.Lock

EonaCat.Lock is a async lock manager for .NET. It allows you to safely lock single or multiple resources asynchronously with minimal boilerplate, while supporting advanced features like hierarchical locks, auto-expiration, reentrancy, deadlock prevention, and telemetry.

• Async/await safe locks – works perfectly in async methods.
• Reentrant locks – the same task can acquire the same lock multiple times safely.
• Global/hierarchical locks – acquire multiple locks atomically in a safe order.
• Auto-expiration / heartbeat – prevent deadlocks by automatically releasing long-held locks.
• Telemetry / metrics – track acquisition counts, max concurrency, and total wait times.
• Optional logging and callbacks – integrate with ILogger or custom actions.
• Minimal boilerplate – use a one-line static API for most scenarios.

Installation

Install via NuGet:

dotnet add package EonaCat.Lock

Or via Package Manager:

Install-Package EonaCat.Lock

Examples

Simple Lock:

    using EonaCat.Lock;
    using System;
    using System.Threading.Tasks;

    class Program
    {
        static async Task Main()
        {
            using (await Lock.LockAsync("ResourceA"))
            {
                Console.WriteLine("Working safely on ResourceA...");
                await Task.Delay(500); // simulate async work
            }
        }
    }

Multiple Resources / Hierarchical Lock

    using EonaCat.Lock;
    using System;
    using System.Threading.Tasks;

    class Program
    {
        static async Task Main()
        {
            using (await Lock.LockMultipleAsync(new[] { "Parent", "Child1", "Child2" }))
            {
                Console.WriteLine("Working safely on multiple resources...");
                await Task.Delay(500);
            }
        }
    }

Advanced Usage

    using EonaCat.Lock;
    using Microsoft.Extensions.Logging;
    using System;
    using System.Threading.Tasks;

    class Program
    {
        static async Task Main()
        {
            var loggerFactory = LoggerFactory.Create(x => x.AddConsole());
            var logger = loggerFactory.CreateLogger<LockManager>();

            var manager = new LockManager(logger);
            manager.LockAcquired += (key, taskId) => Console.WriteLine($"Acquired {key} by task {taskId}");
            manager.LockReleased += (key, taskId) => Console.WriteLine($"Released {key} by task {taskId}");
            manager.LockTimedOut += (key, taskId) => Console.WriteLine($"Timed out {key} for task {taskId}");

            using (await manager.AcquireMultipleAsync(
                new[] { "Parent", "Child1" },
                autoExpireMs: 3000,
                callbackOnAcquire: key => Console.WriteLine($"Callback: Acquired {key}"),
                callbackOnRelease: key => Console.WriteLine($"Callback: Released {key}")
            ))
            {
                Console.WriteLine("Working on hierarchical resources with full telemetry...");
                await Task.Delay(1000);
            }

            var metrics = manager.GetMetrics("Parent");
            Console.WriteLine($"Parent metrics: Total={metrics.totalAcquisitions}, MaxConcurrency={metrics.maxConcurrency}, TotalWaitMs={metrics.totalWaitTimeMs}");
        }
    }