Soenneker.Redis.Semaphores 4.0.12

Soenneker.Redis.Semaphores

A utility library providing distributed semaphores backed by Redis.

Installation

dotnet add package Soenneker.Redis.Semaphores

Registration

services.AddRedisSemaphoreAsScoped();

AddRedisSemaphoreAsSingleton() is also available. Both registrations add Soenneker.Redis.Util and its dependencies.

Usage

Try to acquire a permit without waiting:

RedisSemaphoreHandle? handle = await semaphore.TryAcquire(
    "imports",
    maxCount: 4,
    cancellationToken: cancellationToken);

if (handle is null)
    return;

await using (handle)
{
    await RunImport(cancellationToken);
}

Or wait until a permit becomes available:

await using RedisSemaphoreHandle handle = await semaphore.Acquire(
    "imports",
    maxCount: 4,
    cancellationToken: cancellationToken);

Permits automatically renew while their handles are alive, so the same API supports jobs lasting milliseconds, minutes, or hours. The default one-minute lease measures runner health rather than expected job duration. Disposing the handle stops renewal and releases only its permit. If a runner crashes, renewal stops and Redis recovers the abandoned permit when its lease expires.

Pass the handle's loss token into cooperative work so it stops if Redis ownership can no longer be maintained:

await using RedisSemaphoreHandle handle = await semaphore.Acquire(
    "automation-jobs",
    maxCount: 10,
    cancellationToken: cancellationToken);

using CancellationTokenSource jobCancellation = CancellationTokenSource.CreateLinkedTokenSource(
    cancellationToken,
    handle.PermitLostToken);

await RunJob(jobCancellation.Token);

Lease and retry behavior can be tuned when necessary:

var options = new RedisSemaphoreOptions
{
    LeaseDuration = TimeSpan.FromMinutes(1),
    RenewalInterval = TimeSpan.FromSeconds(20),
    RenewalSafetyMargin = TimeSpan.FromSeconds(10),
    RetryInterval = TimeSpan.FromMilliseconds(100)
};

await using RedisSemaphoreHandle handle = await semaphore.Acquire(
    "automation-jobs",
    maxCount: 10,
    options,
    cancellationToken);

Renewal is owner-safe: Soenneker.Redis.Util uses a Redis transaction to compare the unique permit token and extend its expiration atomically. An expired handle cannot renew or release a permit subsequently acquired by another runner. No Lua scripts are used.

All callers for a semaphore name must use the same maxCount. If PermitLostToken is canceled, the runner should stop the job before the lease can be acquired elsewhere. Semaphore names cannot contain { or } because the library uses Redis hash tags to keep all permit keys for a semaphore in the same cluster slot.

Capacity visibility

Query the distributed permit usage at any time:

RedisSemaphoreStatus status = await semaphore.GetStatus(
    "automation-jobs",
    maxCount: 10,
    cancellationToken);

// status.MaxCount       = 10
// status.AcquiredCount  = permits currently held across all runners
// status.AvailableCount = permits currently available
// status.Utilization    = fraction from 0 through 1
// status.IsFull
// status.IsAvailable

The result is a point-in-time snapshot. Permit state can change immediately after it is read.