Sema v2.0 Acquire Timeout: Unclear Rejection Timing Across Node LTS Releases

Answer: Timeout rejection timing and cancellation

The acquire(timeout) promise in sema v2.0 rejects when the internal setTimeout fires, not exactly after the requested milliseconds. Because Node’s timer resolution can shift by a few milliseconds between LTS releases (due to libuv/V8 updates), the observed delay varies but stays within the typical jitter range of 0‑5 ms.

Likely explanation

Sema v2.0 implements the timeout by wrapping the acquisition attempt in a Promise that is rejected via a setTimeout callback. The actual moment the callback runs depends on the event‑loop’s timer granularity and any pending work, which has changed slightly across Node 12, 14, and 16 LTS lines.

Confirmed fact

In Node.js LTS 14, 16, and 18 the minimum timeout for setTimeout is clamped to 1 ms, but the callback may fire later (typically 1‑5 ms) if the event loop is busy. Sema v2.0 rejects the promise precisely when that timer fires.

Steps to verify timing

1. Create a test script that holds the semaphore for a known short period (e.g., 10 ms) elsewhere.
2. Call sema.acquire(5) and record the start time with process.hrtime.bigint().
3. When the promise rejects, compute the elapsed time and log it.
4. Run the script under Node 12.x, 14.x, and 16.x (or 18.x) and compare the latencies.

If the measured delays fall within the expected jitter (≈0‑5 ms above the requested timeout), the behavior matches Node’s timer implementation.

Cancellation of queued acquires

Sema v2.0 does not provide a built‑in way to cancel a pending acquire(). To avoid accumulating unresolved promises you can:

• Wrap the call in a Promise.race with your own abort signal (e.g., an AbortController) and ignore the sema result if the abort wins.
• Keep a reference to the returned promise and, when cancellation is needed, reject it manually via a wrapper that resolves/rejects based on an external flag.

Best practices for alerting integration

• Set the sema timeout slightly higher than the maximum expected acquisition latency (e.g., add a 5‑10 ms buffer) to reduce false‑positive alerts.
• Debounce or aggregate timeout events before sending notifications to your alerting system.
• Log the actual rejection latency alongside the timeout value so you can detect when jitter exceeds normal bounds.

Missing diagnostic detail

If you observe jitter larger than the typical 0‑5 ms range, check whether the host has any custom timer adjustments (e.g., --max-old-space-size, UV thread‑pool size, or high external load) that could amplify event‑loop delay. Knowing this determines whether the variance is environmental or requires a code‑level fix.