sema acquire/release inside an async request handler: how to prove a missing release is what blocks drain() at shutdown

Answer – what a hanging drain really means

In the current sema releases (≥ v1.4), drain() resolves only when the semaphore’s internal queue of pending acquire promises is empty. If a handler acquires a slot and never releases it (because the code throws before release() or the try/finally is omitted), that slot stays “checked out” forever. The queue never empties, so drain() stays pending. A long‑running request that *does* eventually call release() will also block drain() until the release occurs, but the library treats both situations identically.

1. Is a non‑resolving drain a reliable signal of a leaked acquire?

• Confirmed fact: A hanging drain() guarantees that at least one acquire promise is still queued or an active acquisition hasn’t finished.
• Likely explanation: The most common cause is a missing release() in a try/finally block. Another possibility is that the request is legitimately taking a long time before it releases.
• What it can’t prove: The library does not distinguish between a leaked acquire and a long‑running one; both keep drain() pending.

2. What diagnostics does sema expose?

• The only public surface is nrWaiting(), which reports the number of queued acquire promises. It does not expose per‑waiter timeouts or cancellation hooks.
• To detect leaks, wrap acquire() in a try/finally and log nrWaiting() before and after the critical section.
• For a more granular view, you can instrument your own wrapper that records timestamps for each acquire and checks for unusually long waits.

3. What happens if release() is called more times than acquire()?

• In recent versions, excess releases are silently ignored (the semaphore’s internal count is clamped to the configured maximum). The capacity never grows beyond the original limit.
• Older major releases (< v1.0) allowed over‑release to temporarily increase capacity, but this behaviour was removed to avoid silent resource leaks.
• Therefore, calling release() more times than acquire() is defined behaviour but has no effect other than potentially logging a warning in debug mode.

Practical steps for your scenario

1. Wrap the handler body:

   async function handler(req, res) {
     const sem = await semaphore.acquire();
     try {
       // … work …
     } finally {
       semaphore.release();
     }
   }

2. Before calling drain() at shutdown, log semaphore.nrWaiting() and the number of active acquisitions (if you expose it).
3. If drain() still hangs, check whether any request is still in flight – e.g. by maintaining a counter of active handlers or by inspecting your application logs.

Follow‑up question

To narrow down whether the hang is due to a leak or a long‑running request, could you confirm whether any requests are still actively executing when drain() is invoked?