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
+43 -1
View File
@@ -88,10 +88,52 @@ Samples are immutable PCM16 mono, with a source sample rate and optional loop bo
Linear interpolation uses fractional playback position. With looping off, the next value is the next actual sample frame, or zero beyond the full sample length. With looping on, interpolation across the selected loop end uses the loop-start frame. Playback rate combines source/output sample-rate ratio and pitch. Loop steps may cross multiple repetitions; finite positive pitch, including `f64::MAX`, must not accidentally terminate a short loop or produce an infinite position.
Unloading or replacing a bank does not interrupt a sample already retained by an admitted command or mixer voice. New plays resolve the current bank. Memory can remain retained until the command is cancelled or the playback ends, stops, is replaced, or its session ends. The driver must not retain a second sample reference indefinitely after the mixer observes natural completion.
Unloading or replacing a bank does not interrupt a sample already retained by an admitted command or mixer voice. New plays resolve the current bank. Memory may remain retained after the command is cancelled or playback ends, stops, is replaced, or its session ends, until the host service reclaims the retired owner. Logical inactivity and physical reclamation are separate. The driver must not maintain a second playback mirror that cannot observe completion.
## 7 Host responsibilities and evidence
The desktop host consumes batches, mixes PCM and schedules the physical output. If no output device is available, it consumes committed batches silently. A failed or stalled device is diagnosed and detached so pending publication cannot block the guest indefinitely. The desktop implementation treats two seconds without callback progress as a stalled output.
Headless execution consumes committed batches silently and preserves incomplete frame/callback staging. It validates admission and runtime behavior, without proving audible output. Synthetic mixer tests establish signal behavior; a real device smoke establishes stream initialization and callback consumption, while listening remains a separate observation. Bit-identical PCM across physical devices is not required.
### Bounded desktop reclamation
The successful desktop data callback MUST perform no allocation or deallocation
of runtime-owned memory, including command-vector storage and the last Sample/PCM
owner. This excludes CPAL/device internals and asynchronous driver error reporting.
It is not an absolute device-latency guarantee.
Initialization allocates exactly two retirement packets outside the callback.
Each has room for two returned command-vector owners and 3,088 retired Sample
references: one 1,024-command frame, one combined 2,048-command lifecycle delivery,
and sixteen existing voices. Fixed-capacity SPSC free and return lanes each hold
two packets and MUST NOT grow. A checked-out packet implies a free return slot;
returning it never waits or frees overflow ownership.
The callback MUST obtain a packet before taking a publication. It moves commands
out of vector slots, retaining the vector allocation in the packet, and moves
replaced/stopped/reset voice owners into retirement storage. Stale deliveries are
returned whole. Natural completion marks a voice inactive. Without an available
packet, no publication is taken, accepted commands remain pending under existing
backpressure, and at most sixteen inactive voice slots retain their Sample owners.
Inactive slots produce silence and do not advance. They are existing mixer slots,
not another playback mirror. Pending pause/session transitions apply when the
mixer next obtains a packet and processes control state; already emitted device
buffers cannot be recalled.
`HostAudio::service` MUST drain and recycle packets independently of guest progress,
including paused/backpressured execution, before the next guest attempt. It frees
retired references and clears returned commands outside the callback. Empty vector
storage can be reused through a bounded four-buffer transport cache; excess empty
storage is released on the service lane. These buffers retain no Sample owners.
There is no change to guest quotas, FIFO/prefix order, session epochs, sixteen-voice
capacity, or pause position.
Failed/stalled output is stopped and dropped before silent consumption takes over,
so only one consumer drains the publication transport. Teardown releases callback,
packet and pending-publication ownership outside the data callback. Headless/test
hosts continue consuming silently through the same transport, without constructing
an audio callback or requiring a device.
See [callback qualification](../../vm-arch/audio-callback-qualification.md) for
executed allocation, signal, ownership and device observations.
@@ -0,0 +1,97 @@
# Desktop audio callback qualification
The desktop callback moves discarded Sample references and command-vector owners
into two preallocated return packets. Host service reclaims them outside the data
callback. Logical playback completion does not imply immediate physical release.
The [audio peripheral contract](../specs/runtime/05-audio-peripheral.md) is normative.
## Capacity and ownership proof
One publication can contain 1,024 frame commands and a combined 2,048-command
lifecycle batch. Each command introduces at most one Sample reference, and the
mixer starts with at most sixteen. Therefore at most 3,088 Sample owners can retire
in one callback, even if every command replaces a voice and every resulting voice
finishes immediately. Each packet reserves that reference capacity plus two vector
slots before starting the stream. Stale command references remain in the returned
vectors instead of moving into the retired-reference vector.
Exactly two packets circulate through capacity-two SPSC lanes. While the callback
owns a packet, no more than one other packet can occupy the return lane. Enqueue
therefore needs no waiting, resizing or overflow disposal. Symmetrically, service
can always return a reclaimed packet to the free lane. If both packets await service,
the callback leaves publications untouched. Up to sixteen naturally completed
voices retain owners in their existing slots, becoming silent until reclamation
capacity returns. PCM content can be large; this is a bound on references and fixed
metadata, not an additional PCM byte quota.
Service clears retired references, clears commands and caches at most four empty
command vectors for producer reuse. It runs before guest attempts and during pause
or backpressure. Stream stop/drop precedes silent-consumer takeover. No additional
reclamation worker or playback mirror is introduced.
## Allocation and semantic evidence
`tests/audio_callback_allocations.rs` installs a thread-local allocator counter.
Only runtime callback execution is counted; fixture construction, I/O, reporting,
service reclamation and teardown run outside that region. It counts alloc,
alloc_zeroed, realloc and dealloc (realloc contributes to both counters).
The original last-owner natural completion made zero allocations and two
deallocations; applying a control batch freed one vector. After the change,
debug and release counters report zero allocations/deallocations for natural
completion, all controls, repeated play/stop/replacement, pause, epoch reset,
empty samples, bank unload, 16-voice completion without a packet, ten starved
callbacks and recovery. The saturation case combines 3,072 Play commands with
sixteen existing voices and completion, exercising the full 3,088-owner bound.
Weak-reference assertions prove retention until service and final release.
Unit tests additionally check stale-vector identity and deferred release, 1,000
pool recycling cycles, vector-allocation reuse, bounded empty-buffer caching,
failed/stalled stream takeover and teardown. Existing exact PCM tests retain
one-shot tails, loop seams, fractional interpolation, FIFO/prefix order and pause
position. Runtime audio controls and headless tests retain their logical admission
behavior; the Rust silent-consumer interface remains unchanged.
Reproduce allocation qualification with:
```sh
cargo test -p prometeu-host-desktop-winit --test audio_callback_allocations -- --nocapture
cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations -- --nocapture
```
## Timing observations
Executed on 2026-10-14, macOS/aarch64, rustc 1.98.1, release profile. Both workloads
used sixteen voices and 256 stereo frames at 48 kHz (nominal period 5.333 ms).
The explicitly named pressure workload reads the checked-in stress-console asset
pack and writes a temporary 1 MiB file through HostDirBackend. It does not execute
guest asset decoding or the memcard save scheduler; it is not a substitute for a
separate full integration workload.
| Workload | Callbacks | I/O cycles | p50 | p95 | p99 | Maximum |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| Synthetic callback invocation, interleaved I/O | 1,000 | 1,000 | 13.791 µs | 30.458 µs | 54.292 µs | 72.166 µs |
| MacBook Pro Speakers, concurrent main-thread I/O | 375 | 273 | 11.458 µs | 12.875 µs | 15.916 µs | 30.458 µs |
Both observed zero runtime allocator calls and sixteen live Sample owners before
teardown, zero afterward. Physical buffers were observed at exactly 256 frames.
Timing includes the runtime render call and counter overhead, excludes I/O and
CPAL/device internals, and does not measure device presentation latency. No timing
threshold is asserted. These are local observations, not cross-device certification.
Explicit commands (both timing tests are ignored by ordinary CI):
```sh
cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations callback_duration_16_voices_with_io_pressure -- --ignored --exact --nocapture
cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations physical_callback_duration_16_voices_with_io_pressure -- --ignored --exact --nocapture
cargo test -p prometeu-host-desktop-winit --lib audio::control_tests::desktop_audio_device_smoke -- --ignored --exact --nocapture
```
The ordinary physical smoke passed on retry. The first sandboxed attempt could
not open the device; the first unrestricted attempt received no callbacks and
triggered the existing two-second watchdog. Those failures remain part of the
qualification evidence and demonstrate why successful local timing is not an
availability guarantee. No human listening assessment is claimed.
Strict host Clippy passes. Repository-wide strict-gate status remains separate
from these behavioral and device observations.