Module sync/semaphore

Counting semaphore — Dijkstra's P/V, the same model Java's java.util.concurrent.Semaphore and Rust's tokio::sync::Semaphore carry.

A semaphore holds a non-negative-by-convention count of permits. acquire() takes one permit, blocking while none is available; release() returns one. The count is not capped: release() may be called more times than acquire(), which simply raises the number of permits in flight (this is what makes a semaphore usable as a signalling device and not only as a lock). It is likewise not bound to a thread: the releaser need not be the acquirer, which is precisely what distinguishes it from Mutex.

Acquisition is not fair. A thread that calls acquire() while a permit happens to be available takes it on the spot, even if other threads have been blocked in acquire() for longer — the same barging behaviour as Java's default (non-fair) constructor. There is no FIFO guarantee, and a waiter can in principle be starved under sustained contention. Build fairness on top if you need it.

Typical use is bounding concurrency — at most K threads inside a region:

{ Semaphore } :: import "std/sync/semaphore";
{ Thread } :: import "std/thread";

sem := Semaphore.new(i32(2)); // at most 2 workers in the region
t := Thread(unit).spawn((io) => {
  sem.acquire();
  // ... at most 2 threads are ever here ...
  sem.release();
});
t.join();

Stability

stable — new, acquire, try_acquire, release, with_permit and available_permits follow Java's and tokio's counting-semaphore surface. The two properties most likely to be mistaken for provisional are deliberate and documented above: acquisition is NOT fair, and the permit count is not capped, which is what makes this usable as a signalling device rather than only as a lock. available_permits is a snapshot.