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/1 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 FIFO 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/1 plus a receive with the caller's own timeout. AudioProxy.RenderCoordinator uses request/1 directly, because a coordinator that blocked waiting for a slot could not answer the joins that are coalescing onto it.

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:}. :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.

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.