SSerguey Asael Shinder
Java coding notes: the JVM, and writing software that lasts

Serguey Asael Shinder: Semaphore has no owner: any thread may release, and tryAcquire() ignores fairness

· by Serguey Asael Shinder / Serguey Shinder

FastAPI 0.163, released on 14 November, added Depends(max_concurrency=...), a limit on how many requests can use a dependency at once (release). In Java the standard tool for the same job is java.util.concurrent.Semaphore, and its javadoc for Java SE 25 contains two sentences that are easy to skip and that decide whether such a limit actually holds.

The first is about ownership. The class description says that "no actual permit objects are used; the Semaphore just keeps a count of the number available". A binary semaphore, it adds, can be released "by a thread other than the owner (as semaphores have no notion of ownership)". And release() states: "There is no requirement that a thread that releases a permit must have acquired that permit by calling acquire(). Correct usage of a semaphore is established by programming convention in the application."

Serguey Asael Shinder: Semaphore has no owner: any thread may release, and tryAcquire() ignores fairness
Semaphore has no owner: any thread may release, and tryAcquire() ignores fairness — Serguey Asael Shinder

So the count is only as correct as the code around it. A release() on a path that never acquired adds a permit that was never taken, and the limit quietly grows. A missing release() on an exception path loses a permit for good. The usual shape keeps the two together:

private final Semaphore sessions = new Semaphore(5, true);
<T> T withSession(Function<Session, T> work) throws InterruptedException {
    sessions.acquire();          // outside the try: if this throws, nothing was taken
    try (Session s = openSession()) {
        return work.apply(s);
    } finally {
        sessions.release();      // every path that acquired gives back exactly one
    }
}

The acquire() sits outside the try on purpose: if it is interrupted, no permit was taken, and the finally must not return one.

The second sentence is about fairness. The constructor's fair flag makes acquire hand out permits in FIFO order, but "the untimed tryAcquire methods do not honor the fairness setting, but will take any permits that are available". The tryAcquire() description repeats it - "a call to tryAcquire() will immediately acquire a permit if one is available, whether or not other threads are currently waiting" - and gives the alternative: tryAcquire(0, TimeUnit.SECONDS), which is "almost equivalent (it also detects interruption)" and does honour fairness. The javadoc also recommends fair semaphores for resource access, "to ensure that no thread is starved", and notes that multi-permit acquires establish no preference order unless the semaphore is fair.

One more point follows from the class itself when comparing with FastAPI's design: the count lives in the Semaphore instance. Two components that each create new Semaphore(5) get five permits each, just as two separate Depends(get_session, max_concurrency=5) objects get separate limits. Sharing the limit means sharing the object.