98 lines
5.7 KiB
Markdown
98 lines
5.7 KiB
Markdown
# 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.
|