Show how to use a Semaphore to bound concurrent access to a resource pool, and explain the correctness pitfalls.

## Goal: cap concurrent users of a limited resource Suppose you have a pool of **5 expensive resources** (database connections, file handles, GPU slots). You want at most 5 threads using them at once; the 6th and beyond should wait. A `Semaphore` sized to 5 is exactly the gate. ## A minimal correct pool ```java public final class BoundedPool<T> { private final Semaphore permits; private final Queue<T> items; // thread-safe holder of the real objects public BoundedPool(Collection<T> resources) { this.permits = new Semaphore(resources.size(), true); // fair: FIFO this.items = new ConcurrentLinkedQueue<>(resources); } public T acquire() throws InterruptedException { permits.acquire(); // 1. gate on capacity (blocks past N) return items.poll(); // 2. take an actual item (never null here) } public void release(T item) { if (item == null) return; items.offer(item); // 3. return the object FIRST permits.release(); // 4. THEN release the permit } } ``` ### Why the ordering matters On **release**, return the object to the queue *before* releasing the permit. Otherwise a just-woken thread could `permits.acquire()` succeed, then `items.poll()` and find the queue momentarily empty. On **acquire**, gate the permit *before* polling, so a successful `acquire()` guarantees an item is present (invariant: free-permit-count == items-in-queue). ## The standard call site ```java T r = pool.acquire(); try { use(r); } finally { pool.release(r); // ALWAYS, even on exception } ``` ## Pitfall 1 — release outside `finally` (permit leak) ```java sem.acquire(); use(r); // if this throws... sem.release(); // ...this never runs -> permit leaked forever ``` Each leak permanently lowers capacity. After 5 leaks on a `Semaphore(5)`, *every* `acquire()` blocks forever — a slow-motion **deadlock** that's hard to diagnose because nothing crashes; threads just pile up. Fix: `release()` in `finally`. ## Pitfall 2 — release without acquire (over-release) ```java if (sem.tryAcquire()) { /* ... */ } finally { sem.release(); } // BUG: releases even when tryAcquire returned false ``` Because a semaphore has no owner and `release()` blindly increments the count, this **inflates** permits above the intended N. Now 6, 7, … threads slip past the gate and the capacity bound is silently broken — you might exhaust the underlying resource and get errors that look unrelated. Fix: only release on the path that actually acquired. ```java boolean got = sem.tryAcquire(); if (got) { try { /* ... */ } finally { sem.release(); } } ``` ## Pitfall 3 — confusing counting with ownership A `Semaphore` only **counts**; it does not know *which* object a thread holds or even *which* thread holds a permit. So you must keep the real pooled objects in a separate thread-safe structure and never assume the semaphore tracks identity. It guards the *number* of concurrent holders, full stop. ## Why a semaphore and not just a lock or a blocking queue? - A `ReentrantLock` allows only one holder — wrong shape for N. - A `BlockingQueue` of N items *is* a valid alternative pool (take/put block on capacity) and is often preferred because the item and the permit are unified. The semaphore version shines when the permit and the resource are conceptually separate, or when you want timed/fail-fast admission (`tryAcquire`) and a tunable fairness policy independent of the data structure. ## Fairness for pools A **fair** semaphore (`new Semaphore(n, true)`) serves waiters FIFO, preventing a thread from **starving** (waiting indefinitely while latecomers barge). For a pool under steady contention, fairness gives predictable latency at a small throughput cost; non-fair maximises throughput but can starve unlucky threads.