perf(audio): reclaim callback owners through bounded return packets

This commit is contained in:
2026-10-14 11:59:47 +01:00
parent 46bbad19c2
commit 461b554c1a
9 changed files with 909 additions and 29 deletions
@@ -77,3 +77,37 @@ The API is a foreground PCM control surface. It does not establish musical seque
- Keep shutdown, pause and session invalidation independent of guest saturation.
- Place completion-sensitive state with the component that actually observes completion.
- Test both explicit and implicit runtime boundaries, including debugger transitions.
## Completion and Reclamation Have Different Owners
The callback reclamation correction derives from DEC-0062. A nonblocking mailbox
alone did not make the callback allocator-free: dropping a consumed Vec freed its
storage, and finishing a voice could free the final Sample and PCM allocation.
The useful boundary is ownership destruction, not just explicit allocation calls.
Two preallocated packets now move discarded references and vector allocations to
main-thread service. The bound follows from admitted input: 1,024 frame commands,
2,048 combined lifecycle commands and sixteen initial voices imply at most 3,088
retired owners and two vectors per packet. Conservation, rather than an overflow
fallback, guarantees room to return a packet. When both await service, publications
remain pending and naturally finished voices become silent while retaining at most
sixteen references in their existing slots. A stalled reclaimer cannot create an
unbounded queue or resurrect a finished voice.
The original signal observations above remain valid, but physical release now
happens during service. Service runs before guest attempts even during pause or
backpressure. It clears retired owners and reuses bounded empty command storage.
Stream shutdown precedes silent consumption, preserving a single transport consumer.
Tests distinguish logical silence, delayed retention and eventual destruction with
weak references; owner release is no longer inferred merely from silent PCM.
The [callback qualification](../../../docs/vm-arch/audio-callback-qualification.md)
records zero runtime allocator calls in debug/release paths, the capacity-saturation
case and local device timing. A physical release run observed 375 callbacks on
MacBook Pro Speakers with 256-frame buffers and a 30.458 µs maximum runtime duration;
all sixteen owners released at teardown. Its asset-pack reads and temporary 1 MiB
host-file writes are an explicitly limited pressure workload, not guest save or
asset-pipeline certification. Earlier device-open/stall failures are retained in
the evidence rather than erased by a successful retry. The
[audio specification](../../../docs/specs/runtime/05-audio-peripheral.md) defines
the bounded reclamation contract; timing measurements do not define device deadlines.