perf(audio): reclaim callback owners through bounded return packets
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user