Lyo.Lock 1.0.1

Lyo.Lock

Key-based exclusive locks and keyed semaphores (bounded concurrency per key) with a small abstraction layer and in-memory implementations for a single process.

Features

• ILockService — acquire/release by string key, or ExecuteWithLockAsync helpers that throw TimeoutException if the lock is not obtained.
• LocalLockService — one holder per normalized key using SemaphoreSlim.
• IKeyedSemaphoreService — up to maxConcurrency simultaneous permit holders per key.
• LocalKeyedSemaphoreService — per-key SemaphoreSlim with ref-counted cleanup when idle.
• Key normalization — by default keys are compared case-insensitively (ToLowerInvariant); optional skip when keys are already normalized.
• DI — AddLocalLock, AddLocalLockFromConfiguration, AddLocalKeyedSemaphore, AddLocalKeyedSemaphoreFromConfiguration.
• Metrics — optional timers/counters via Lyo.Metrics when EnableMetrics is true and IMetrics is registered.

Examples

Quick start

using Lyo.Lock;
using Microsoft.Extensions.DependencyInjection;

services.AddLocalLock();
services.AddLocalKeyedSemaphore();

// Optional: bind appsettings → LockOptions / KeyedSemaphoreOptions
services.AddLocalLockFromConfiguration(configuration);
services.AddLocalKeyedSemaphoreFromConfiguration(configuration);

Quick start (2)

// Exclusive lock: null if timeout
var handle = await lockService.AcquireAsync("order:123", timeout: TimeSpan.FromSeconds(5));
if (handle is not null)
{
    await using (handle)
        await ProcessOrderAsync();
}

// Throws TimeoutException if not acquired
await lockService.ExecuteWithLockAsync("order:123", async ct => await ProcessOrderAsync(ct));

// Up to 3 concurrent operations for the same key (same process only)
await semaphoreService.ExecuteAsync("export:tenant-1", 3, async ct => await RunExportAsync(ct));

KeyedSemaphoreOptions (KeyedSemaphoreOptions section)

{
  "LockOptions": {
    "DefaultAcquireTimeout": "00:00:30",
    "DefaultLockDuration": "00:01:00",
    "KeyPrefix": "lyo:lock:",
    "EnableMetrics": false,
    "SkipKeyNormalization": false
  },
  "KeyedSemaphoreOptions": {
    "DefaultAcquireTimeout": "00:00:30",
    "SkipKeyNormalization": false,
    "EnableMetrics": false
  }
}

Benchmarks

• Portfolio suite: lock

When to use what

For multiple servers or processes, register a distributed ILockService (see Lyo.Lock.Redis). Keyed semaphores in this package remain local only.

Quick start

Inject ILockService and/or IKeyedSemaphoreService:

Rules for keyed semaphores

• Use a stable maxConcurrency for a given key while any permit is held or waiters exist. If you pass a different maxConcurrency for an active key, LocalKeyedSemaphoreService throws (InvalidOperationException) instead of undefined behavior.
• Cancellation tokens on AcquireAsync / ExecuteAsync are honored while waiting.

LockOptions (LockOptions section)

KeyedSemaphoreOptions (KeyedSemaphoreOptions section)

Example appsettings.json:

Metrics (Constants)

When metrics are enabled and IMetrics is registered, names match Lyo.Lock.Constants:

Locks (Constants.Metrics)

Semaphores (Constants.SemaphoreMetrics)

Tag dimension: key — logical key string as passed by the caller (see XML docs on Constants).

API summary — ILockService

• AcquireAsync — returns ILockHandle? (null on timeout).
• ExecuteWithLockAsync / ExecuteWithLockAsync<T> — acquire, run delegate, release; throw TimeoutException if not acquired.

API summary — ILockHandle / IPermitHandle

• ReleaseAsync — idempotent after first release.
• Dispose / DisposeAsync — release (sync dispose may block briefly on internal ReleaseAsync).

API summary — IKeyedSemaphoreService

• AcquireAsync — returns IPermitHandle? on timeout.
• ExecuteAsync / ExecuteAsync<T> — throw TimeoutException if no permit.

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Exceptions — (direct, lyo)
• Lyo.Metrics — (direct, lyo)
• Microsoft.Extensions.Configuration.Binder 10.0.5 — (direct, microsoft)
• Microsoft.Extensions.DependencyInjection.Abstractions 10.0.5 — (direct, microsoft)
• Microsoft.Extensions.Logging.Abstractions 10.0.5 — (direct, microsoft)
• Microsoft.Extensions.Options.ConfigurationExtensions 10.0.5 — (transitive, microsoft)