The render-slot budget: at most AP_MAX_CONCURRENCY renders at once, with at most AP_QUEUE_SIZE waiting behind them.

ffmpeg is CPU-bound, so the number of encoders running at once is the one resource this proxy has to ration. Everything else — the coalescing registry, the bounded buffers, the kill discipline — assumes a slot was granted first. A request that cannot get one and cannot wait for one is a 429, which is the only place §5's Retry-After comes from.

The server never blocks

request/2 is a GenServer.call that answers immediately with one of three outcomes:

• :granted — a slot was free and the caller now holds it
• :queued — the caller is in the wait queue and will receive {AudioProxy.Semaphore, :granted} when its turn comes
• {:error, {:queue_full, retry_after}} — no slot, no room to wait

Grants happen inside release/1 and DOWN handling, never in a callback that waits for something. That is what lets a caller queue for minutes without the semaphore being unable to answer anyone else — including the releases that are the only way the queue ever moves.

acquire/1 is the blocking convenience on top: request/2 plus a receive with the caller's own timeout. AudioProxy.RenderCoordinator uses request/2 directly, because a coordinator that blocked waiting for a slot could not answer the joins that are coalescing onto it.

Admission classes

The wait queue is ordered rather than flat: interactive > high > normal > low. A freed slot goes to the oldest waiter of the highest non-empty class, and FIFO holds within a class, so classes/0 is a tie-breaking order on top of arrival order rather than a replacement for it.

interactive is the default, which is what makes the whole mechanism invisible: a caller that says nothing is in the one class nothing can outrank and nothing can displace, queued behind exactly the callers that were already in front of it. A workload where nobody speaks a class is plain FIFO, and AudioProxy.SemaphorePropertyTest compares it against a FIFO model to keep it that way. Nothing in this repository passes :class today; the classes exist for callers that have background work to defer — cache warming, batch rendering — and want it to yield to a live listener.

When the queue is full, an arrival that outranks something queued displaces the newest waiter of the lowest non-interactive class present: the newest has waited least, so displacing it wastes the least sunk waiting. The victim receives {AudioProxy.Semaphore, {:displaced, retry_after}} — a reply distinct from queue-full, and retryable the same way. An arrival that outranks nothing queued is refused with {:queue_full, retry_after}, exactly as before.

Starvation of the lower classes is the contract, not a defect. There is no aging: under sustained interactive load, low waits indefinitely and is displaced first. That is safe because deferred work is not lost — a render that never got its background slot is still rendered lazily the moment someone asks for it directly — and it is visible, because every event carries per-class depth. A scheduler that let batch work overtake a listener would be trading the one latency the proxy is judged on for throughput nobody is waiting on.

One slot per process, released by exit if not by hand

A holder is monitored, and its DOWN releases the slot — so a crashed render costs a slot for as long as the monitor takes to fire, and no longer. A queued waiter is monitored too, and its DOWN drops it from the queue, so a client that gives up while waiting does not get handed a slot nobody is holding.

release/1 is therefore a promptness optimisation rather than the guarantee, and it is idempotent: releasing twice, or releasing without holding, is :ok. The one thing the monitor cannot cover is a long-lived caller whose release did not reach a wedged semaphore — see release/1. Acquiring twice from one process is {:error, :already_held} — a slot is a process' budget, and a second one would be an accounting error rather than a deadlock worth waiting on.

The caller-timeout race

A grant can land in the window between acquire/1's timeout firing and the caller doing anything about it. acquire/1 closes it by releasing and then draining: release/1 is synchronous, so by the time it returns the server has processed it and any grant it sent is already in the mailbox — the drain is exact rather than a race of its own.

Configuration is read per operation

Capacity and queue size come from AudioProxy.Config on every call, not from init/1. There is no reconfiguration at runtime, so in production this is just a :persistent_term read; in tests it means put_config/1 takes effect without restarting a supervised process. Lowering capacity below the number of slots currently held grants nothing new until it drains, which is the only sensible reading of it.

Tests that want a semaphore of their own can pass :name, :capacity and :queue_size to start_link/1, which pins them and skips the config read.

Retry-After

Derived from a moving average of recent slot-hold durations, scaled by how deep the queue already is: roughly "how long the renders in front of you have been taking, times how many of them there are, over how many run at once". Coarse by construction — §5 only requires the header to exist and be sane, and a client that retries a little early finds the queue full again and is told again. Before any render has completed there is nothing to average, so a placeholder stands in until the first one does.

Events

held and queued are the occupancy and depth after the event; wait and duration are native time units. Metadata is always %{capacity:, queue_size:, class:}, where class is the class of whoever the event is about — the caller granted, queued, rejected or displaced, or the holder that released. :abandoned is one more event than design.md listed, and it is here so that a queue draining by attrition — clients giving up — does not leave queued reading high until the next unrelated event.

Every event also carries queued_interactive, queued_high, queued_normal and queued_low: the depth of each class, not just the one the event is about. Reporting only the event's own class would publish a low depth that goes stale for as long as low is starved — which is precisely the state an operator needs to see, and precisely when no low event fires.

AudioProxy.Metrics counts :rejected from this set and takes its occupancy gauges from stats/2 instead, so the accuracy of what it publishes does not depend on every event being seen.