What is SemaphoreSlim, and how do you use it as an async lock or to throttle concurrent async work?

1. How it works inside

SemaphoreSlim
 ├─ m_currentCount        free slots
 ├─ m_maxCount
 ├─ m_lockObjAndDisposed  internal Monitor for sync waiters
 └─ m_asyncHead/m_asyncTail  linked list of TaskNode (async waiters)

WaitAsync():
   lock internal; if count > 0 -> count--, return completed task (no allocation in common case)
   else -> append TaskNode (a Task<bool>) to the async list, register cancellation/timeout, return it
Release():
   lock internal; if async waiters -> complete the head TaskNode (asynchronously) ; else count++

• Uncontended WaitAsync returns an already-completed cached task.
• Synchronous Wait() spins briefly before blocking on the internal monitor.
• Released async waiters are completed so their continuations run on the pool, not inline inside Release.

2. Non-reentrancy deadlock

public async Task SaveAsync()
{
    await _gate.WaitAsync();
    try { await ValidateAsync(); }   // ValidateAsync also does await _gate.WaitAsync() -> waits forever
    finally { _gate.Release(); }
}

Design rule: public entry points take the gate; private helpers assume it's held (document it, or pass a token/marker parameter).

3. Release discipline

// WRONG: Release runs even if WaitAsync threw (cancelled) -> count increases
try
{
    await _gate.WaitAsync(ct);
    await WorkAsync(ct);
}
finally { _gate.Release(); }

// RIGHT
await _gate.WaitAsync(ct);
try { await WorkAsync(ct); }
finally { _gate.Release(); }

Passing maxCount to the constructor turns an accidental extra release into a loud SemaphoreFullException instead of silently raising concurrency.

4. A disposable helper

public static class SemaphoreExtensions
{
    public static async ValueTask<Releaser> LockAsync(this SemaphoreSlim s, CancellationToken ct = default)
    {
        await s.WaitAsync(ct).ConfigureAwait(false);
        return new Releaser(s);
    }

    public readonly struct Releaser(SemaphoreSlim s) : IDisposable
    {
        public void Dispose() => s.Release();
    }
}

using (await _gate.LockAsync(ct))
{
    await SaveAsync(ct);
}

5. Per-key locks

To serialise work per entity (per customer id), people create ConcurrentDictionary<string, SemaphoreSlim>. The trap: entries are never removed and the dictionary grows forever. Use reference counting and removal, a striped approach (semaphores[hash % N]), or a library such as AsyncKeyedLock.

6. Observability

Export CurrentCount (or max - CurrentCount as "in use") and wait time as metrics. A throttle that's always at zero free slots means the dependency is the bottleneck, or the limit is too low.

7. Version notes

8. Try it yourself

1. Run the code example: peak concurrency is 5 and the cache loads once.
2. Remove the double-check in RefreshingCache and count loads.
3. Put the WaitAsync inside the try, cancel some waits, and watch CurrentCount exceed the initial count (or throw with maxCount).
4. Call a method that re-acquires the same gate and observe the deadlock.
5. Rewrite the 50-task loop with Parallel.ForEachAsync(..., new ParallelOptions { MaxDegreeOfParallelism = 5 }, ...).
6. Implement the LockAsync helper and use it with using.

using System.Threading;

var limiter = new SemaphoreSlim(initialCount: 5, maxCount: 5);
int inside = 0, peak = 0;

var tasks = Enumerable.Range(1, 50).Select(async id =>
{
    await limiter.WaitAsync();
    try
    {
        int now = Interlocked.Increment(ref inside);
        InterlockedMax(ref peak, now);
        await Task.Delay(200); // stands in for an HTTP call
    }
    finally
    {
        Interlocked.Decrement(ref inside);
        limiter.Release();
    }
});

await Task.WhenAll(tasks);
Console.WriteLine($"Peak concurrency: {peak}"); // 5

var cache = new RefreshingCache();
await Task.WhenAll(Enumerable.Range(0, 10).Select(_ => cache.GetAsync()));
Console.WriteLine($"Loads: {cache.Loads}"); // 1

static void InterlockedMax(ref int target, int value)
{
    int current;
    while (value > (current = Volatile.Read(ref target)) &&
           Interlocked.CompareExchange(ref target, value, current) != current) { }
}

public sealed class RefreshingCache
{
    private readonly SemaphoreSlim _gate = new(1, 1);
    private string? _value;
    public int Loads;

    public async Task<string> GetAsync(CancellationToken ct = default)
    {
        if (_value is { } v) return v;
        await _gate.WaitAsync(ct);
        try
        {
            if (_value is { } again) return again; // double-check after acquiring
            await Task.Delay(100, ct);             // load once
            Interlocked.Increment(ref Loads);
            return _value = "loaded";
        }
        finally
        {
            _gate.Release();
        }
    }
}