perf(audio): reclaim callback owners through bounded return packets
This commit is contained in:
@@ -203,7 +203,8 @@ impl AudioBridge for Audio {
|
||||
fn begin_frame(&mut self) { /* Staging may already contain debugger steps. */
|
||||
}
|
||||
fn finish_frame(&mut self) {
|
||||
self.transport.publish(std::mem::take(&mut self.commands), false);
|
||||
let commands = std::mem::replace(&mut self.commands, self.transport.take_buffer());
|
||||
self.transport.publish(commands, false);
|
||||
self.frame_commands_admitted = 0;
|
||||
}
|
||||
fn abort_frame(&mut self) {
|
||||
@@ -221,7 +222,7 @@ impl AudioBridge for Audio {
|
||||
if success {
|
||||
// Publish the earlier frame prefix first so a callback stop cannot
|
||||
// be undone by an old play on resume. Do not replenish frame quota.
|
||||
let mut commands = std::mem::take(&mut self.commands);
|
||||
let mut commands = std::mem::replace(&mut self.commands, self.transport.take_buffer());
|
||||
commands.append(&mut self.lifecycle_commands);
|
||||
self.transport.publish(commands, true);
|
||||
} else {
|
||||
|
||||
@@ -14,6 +14,7 @@ struct Mailbox {
|
||||
paused: bool,
|
||||
frame: Option<Vec<AudioCommand>>,
|
||||
lifecycle: Option<Vec<AudioCommand>>,
|
||||
recycled: [Option<Vec<AudioCommand>>; 4],
|
||||
}
|
||||
|
||||
pub struct AudioDelivery {
|
||||
@@ -36,7 +37,31 @@ impl AudioTransport {
|
||||
}
|
||||
|
||||
pub fn consume_silently(&self) {
|
||||
let _ = self.try_take();
|
||||
if let Some(delivery) = self.try_take() {
|
||||
for batch in [delivery.frame, delivery.lifecycle].into_iter().flatten() {
|
||||
self.recycle_commands(batch);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Main/service lane only: drop command owners and retain bounded empty storage.
|
||||
pub fn recycle_commands(&self, mut commands: Vec<AudioCommand>) {
|
||||
commands.clear();
|
||||
let mut state = self.0.lock().expect("audio mailbox");
|
||||
if let Some(slot) = state.recycled.iter_mut().find(|slot| slot.is_none()) {
|
||||
*slot = Some(commands);
|
||||
}
|
||||
// Excess empty buffers are destroyed here, never in the data callback.
|
||||
}
|
||||
|
||||
pub(super) fn take_buffer(&self) -> Vec<AudioCommand> {
|
||||
self.0
|
||||
.lock()
|
||||
.expect("audio mailbox")
|
||||
.recycled
|
||||
.iter_mut()
|
||||
.find_map(Option::take)
|
||||
.unwrap_or_default()
|
||||
}
|
||||
|
||||
pub fn ready(&self) -> bool {
|
||||
@@ -84,3 +109,36 @@ mod tests {
|
||||
assert!(transport.try_take().is_some());
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod reuse_tests {
|
||||
use super::*;
|
||||
#[test]
|
||||
fn service_recycles_storage_and_releases_sample_owners() {
|
||||
use prometeu_hal::{LoopMode, sample::Sample};
|
||||
let transport = AudioTransport::default();
|
||||
let sample = Arc::new(Sample::new(48000, vec![1]));
|
||||
let weak = Arc::downgrade(&sample);
|
||||
let mut batch = Vec::with_capacity(1024);
|
||||
let allocation = batch.as_ptr();
|
||||
batch.push(AudioCommand::Play {
|
||||
sample,
|
||||
voice_id: 0,
|
||||
volume: 255,
|
||||
pan: 0,
|
||||
pitch: 1.0,
|
||||
priority: 0,
|
||||
loop_mode: LoopMode::Off,
|
||||
});
|
||||
transport.recycle_commands(batch);
|
||||
assert!(weak.upgrade().is_none());
|
||||
let reused = transport.take_buffer();
|
||||
assert_eq!(reused.as_ptr(), allocation);
|
||||
assert_eq!(reused.capacity(), 1024);
|
||||
assert!(reused.is_empty());
|
||||
for _ in 0..8 {
|
||||
transport.recycle_commands(Vec::with_capacity(16));
|
||||
}
|
||||
assert_eq!(transport.0.lock().unwrap().recycled.iter().flatten().count(), 4);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
mod reclamation;
|
||||
pub use reclamation::AudioReclaimer;
|
||||
use reclamation::{CallbackLane, Packet};
|
||||
|
||||
use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
|
||||
use prometeu_drivers::{AudioCommand, Channel, MAX_CHANNELS, OUTPUT_SAMPLE_RATE};
|
||||
use prometeu_drivers::{AudioDelivery, AudioTransport};
|
||||
@@ -10,9 +14,15 @@ use std::sync::Arc;
|
||||
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
trait AudioStreamHandle {}
|
||||
trait AudioStreamHandle {
|
||||
fn stop(&self) {}
|
||||
}
|
||||
|
||||
impl AudioStreamHandle for cpal::Stream {}
|
||||
impl AudioStreamHandle for cpal::Stream {
|
||||
fn stop(&self) {
|
||||
let _ = self.pause();
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum HostAudioError {
|
||||
@@ -97,6 +107,7 @@ pub struct HostAudio {
|
||||
last_progress: Instant,
|
||||
pub perf_consumer: Option<ringbuf::wrap::CachingCons<Arc<HeapRb<u64>>>>,
|
||||
_stream: Option<Box<dyn AudioStreamHandle>>,
|
||||
reclaimer: Option<AudioReclaimer>,
|
||||
}
|
||||
|
||||
impl Default for HostAudio {
|
||||
@@ -115,6 +126,7 @@ impl HostAudio {
|
||||
last_progress: Instant::now(),
|
||||
perf_consumer: None,
|
||||
_stream: None,
|
||||
reclaimer: None,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -129,7 +141,7 @@ impl HostAudio {
|
||||
self.last_heartbeat = 0;
|
||||
self.last_progress = Instant::now();
|
||||
self.perf_consumer = None;
|
||||
self._stream = None;
|
||||
self.stop_stream();
|
||||
|
||||
let device = runtime.default_output_device().ok_or(HostAudioError::NoOutputDevice)?;
|
||||
|
||||
@@ -143,7 +155,7 @@ impl HostAudio {
|
||||
let failed = self.failed.clone();
|
||||
let heartbeat = self.heartbeat.clone();
|
||||
|
||||
let mut mixer = AudioMixer::new();
|
||||
let (mut callback, reclaimer) = AudioCallback::new();
|
||||
|
||||
// To pass performance data from the audio thread to the main thread
|
||||
let audio_perf_rb = HeapRb::<u64>::new(64);
|
||||
@@ -154,13 +166,9 @@ impl HostAudio {
|
||||
&config,
|
||||
move |data: &mut [f32]| {
|
||||
heartbeat.fetch_add(1, Ordering::Relaxed);
|
||||
if let Some(delivery) = transport.try_take() {
|
||||
mixer.apply_delivery(delivery);
|
||||
}
|
||||
// Mixes audio
|
||||
mixer.fill_buffer(data);
|
||||
callback.render(&transport, data);
|
||||
// Sends processing time in microseconds
|
||||
let _ = perf_prod.try_push(mixer.last_processing_time.as_micros() as u64);
|
||||
let _ = perf_prod.try_push(callback.mixer.last_processing_time.as_micros() as u64);
|
||||
},
|
||||
move |err| {
|
||||
failed.store(true, Ordering::Relaxed);
|
||||
@@ -169,6 +177,7 @@ impl HostAudio {
|
||||
)?;
|
||||
|
||||
runtime.play_stream(&stream)?;
|
||||
self.reclaimer = Some(reclaimer);
|
||||
self.perf_consumer = Some(perf_cons);
|
||||
self._stream = Some(Box::new(stream));
|
||||
Ok(())
|
||||
@@ -177,6 +186,9 @@ impl HostAudio {
|
||||
/// Called even while guest execution is backpressured. A failed or stalled
|
||||
/// device cannot retain the only publication slot indefinitely.
|
||||
pub fn service(&mut self) {
|
||||
if let Some(reclaimer) = &mut self.reclaimer {
|
||||
reclaimer.service(&self.transport);
|
||||
}
|
||||
let heartbeat = self.heartbeat.load(Ordering::Relaxed);
|
||||
if heartbeat != self.last_heartbeat {
|
||||
self.last_heartbeat = heartbeat;
|
||||
@@ -187,7 +199,7 @@ impl HostAudio {
|
||||
|| self.last_progress.elapsed() >= Duration::from_secs(2))
|
||||
{
|
||||
eprintln!("[HostAudio] Output unavailable/stalled; consuming audio silently.");
|
||||
self._stream = None;
|
||||
self.stop_stream();
|
||||
self.perf_consumer = None;
|
||||
}
|
||||
if self._stream.is_none() {
|
||||
@@ -195,6 +207,16 @@ impl HostAudio {
|
||||
}
|
||||
}
|
||||
|
||||
fn stop_stream(&mut self) {
|
||||
if let Some(stream) = self._stream.take() {
|
||||
stream.stop();
|
||||
drop(stream); // Stop/drop the callback before any silent consumer takes over.
|
||||
}
|
||||
if let Some(mut reclaimer) = self.reclaimer.take() {
|
||||
reclaimer.service(&self.transport);
|
||||
}
|
||||
}
|
||||
|
||||
pub fn update_stats(&mut self, stats: &mut crate::stats::HostStats) {
|
||||
if let Some(cons) = &mut self.perf_consumer {
|
||||
while let Some(us) = cons.try_pop() {
|
||||
@@ -204,6 +226,40 @@ impl HostAudio {
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for HostAudio {
|
||||
fn drop(&mut self) {
|
||||
self.stop_stream();
|
||||
self.transport.consume_silently();
|
||||
}
|
||||
}
|
||||
|
||||
/// The same bounded runtime-owned data path used by CPAL and allocator tests.
|
||||
pub struct AudioCallback {
|
||||
mixer: AudioMixer,
|
||||
lane: CallbackLane,
|
||||
}
|
||||
impl AudioCallback {
|
||||
pub fn new() -> (Self, AudioReclaimer) {
|
||||
let (lane, reclaimer) = reclamation::pool();
|
||||
(Self { mixer: AudioMixer::new(), lane }, reclaimer)
|
||||
}
|
||||
pub fn render(&mut self, transport: &AudioTransport, data: &mut [f32]) {
|
||||
let mut packet = self.lane.take();
|
||||
if let Some(packet) = &mut packet {
|
||||
// Reserve reclamation before acquiring any publication ownership.
|
||||
self.mixer.retire_inactive(packet);
|
||||
if let Some(delivery) = transport.try_take() {
|
||||
self.mixer.apply_delivery_into(delivery, packet);
|
||||
}
|
||||
}
|
||||
self.mixer.mix(data);
|
||||
if let Some(mut packet) = packet {
|
||||
self.mixer.retire_inactive(&mut packet);
|
||||
self.lane.give_back(packet);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
#[allow(clippy::items_after_test_module)]
|
||||
mod tests {
|
||||
@@ -347,27 +403,59 @@ impl AudioMixer {
|
||||
}
|
||||
}
|
||||
|
||||
pub fn apply_delivery(&mut self, delivery: AudioDelivery) {
|
||||
fn apply_delivery_into(&mut self, delivery: AudioDelivery, packet: &mut Packet) {
|
||||
if delivery.epoch < self.epoch {
|
||||
packet.batches = [delivery.frame, delivery.lifecycle];
|
||||
return;
|
||||
}
|
||||
if delivery.epoch != self.epoch {
|
||||
self.voices = Default::default();
|
||||
for voice in &mut self.voices {
|
||||
packet.retire(voice.sample.take());
|
||||
*voice = Channel::default();
|
||||
}
|
||||
self.epoch = delivery.epoch;
|
||||
}
|
||||
// A frame pending before a lifecycle hook is always applied first.
|
||||
for batch in [delivery.frame, delivery.lifecycle].into_iter().flatten() {
|
||||
for command in batch {
|
||||
self.process_command(command);
|
||||
for (slot, batch) in packet.batches.iter_mut().zip([delivery.frame, delivery.lifecycle]) {
|
||||
*slot = batch;
|
||||
}
|
||||
// Move commands out of slots, keeping each vector allocation in its packet.
|
||||
for index in 0..2 {
|
||||
if let Some(mut batch) = packet.batches[index].take() {
|
||||
for command in &mut batch {
|
||||
let command =
|
||||
std::mem::replace(command, AudioCommand::Stop { voice_id: MAX_CHANNELS });
|
||||
self.process_command(command, packet);
|
||||
}
|
||||
packet.batches[index] = Some(batch);
|
||||
}
|
||||
}
|
||||
self.paused = delivery.paused;
|
||||
}
|
||||
|
||||
pub fn process_command(&mut self, cmd: AudioCommand) {
|
||||
fn retire_inactive(&mut self, packet: &mut Packet) {
|
||||
for voice in &mut self.voices {
|
||||
if !voice.active {
|
||||
packet.retire(voice.sample.take());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Signal-only tests use synchronous reclamation outside a data callback.
|
||||
#[cfg(test)]
|
||||
fn apply_delivery(&mut self, delivery: AudioDelivery) {
|
||||
self.apply_delivery_into(delivery, &mut Packet::new());
|
||||
}
|
||||
#[cfg(test)]
|
||||
fn fill_buffer(&mut self, buffer: &mut [f32]) {
|
||||
self.mix(buffer);
|
||||
self.retire_inactive(&mut Packet::new());
|
||||
}
|
||||
|
||||
fn process_command(&mut self, cmd: AudioCommand, packet: &mut Packet) {
|
||||
match cmd {
|
||||
AudioCommand::Play { sample, voice_id, volume, pan, pitch, priority, loop_mode } => {
|
||||
if voice_id < MAX_CHANNELS {
|
||||
packet.retire(self.voices[voice_id].sample.take());
|
||||
self.voices[voice_id] = Channel {
|
||||
sample: Some(sample),
|
||||
active: true,
|
||||
@@ -378,12 +466,14 @@ impl AudioMixer {
|
||||
loop_mode,
|
||||
priority,
|
||||
};
|
||||
} else {
|
||||
packet.retire(Some(sample));
|
||||
}
|
||||
}
|
||||
AudioCommand::Stop { voice_id } => {
|
||||
if voice_id < MAX_CHANNELS {
|
||||
self.voices[voice_id].active = false;
|
||||
self.voices[voice_id].sample = None;
|
||||
packet.retire(self.voices[voice_id].sample.take());
|
||||
}
|
||||
}
|
||||
AudioCommand::SetVolume { voice_id, volume } => {
|
||||
@@ -404,7 +494,7 @@ impl AudioMixer {
|
||||
}
|
||||
}
|
||||
|
||||
pub fn fill_buffer(&mut self, buffer: &mut [f32]) {
|
||||
fn mix(&mut self, buffer: &mut [f32]) {
|
||||
let start = std::time::Instant::now();
|
||||
// Zeroes the buffer (stereo)
|
||||
for sample in buffer.iter_mut() {
|
||||
@@ -417,13 +507,15 @@ impl AudioMixer {
|
||||
}
|
||||
|
||||
for voice in self.voices.iter_mut() {
|
||||
if !voice.active {
|
||||
continue;
|
||||
}
|
||||
let Some(sample) = voice.sample.as_ref() else {
|
||||
continue;
|
||||
};
|
||||
let len = sample.data.len();
|
||||
if len == 0 {
|
||||
voice.active = false;
|
||||
voice.sample = None;
|
||||
continue;
|
||||
}
|
||||
let (loop_start, end) = match (voice.loop_mode, sample.loop_start, sample.loop_end) {
|
||||
@@ -441,7 +533,6 @@ impl AudioMixer {
|
||||
let pos = voice.pos as usize;
|
||||
if pos >= len {
|
||||
voice.active = false;
|
||||
voice.sample = None;
|
||||
break;
|
||||
}
|
||||
let s1 = sample.data[pos] as f32 / 32768.0;
|
||||
@@ -460,7 +551,6 @@ impl AudioMixer {
|
||||
if voice.pitch >= (end - voice.pos) / ratio {
|
||||
if voice.loop_mode == LoopMode::Off {
|
||||
voice.active = false;
|
||||
voice.sample = None;
|
||||
break;
|
||||
}
|
||||
let length = end - loop_start;
|
||||
@@ -867,6 +957,7 @@ mod control_tests {
|
||||
audio.finish_frame();
|
||||
let deadline = Instant::now() + Duration::from_secs(2);
|
||||
while !audio.ready() && Instant::now() < deadline {
|
||||
host.service();
|
||||
std::thread::sleep(Duration::from_millis(10));
|
||||
}
|
||||
assert!(audio.ready());
|
||||
@@ -875,12 +966,119 @@ mod control_tests {
|
||||
audio.set_pan(0, 255);
|
||||
audio.set_pitch(0, 1.5);
|
||||
audio.finish_frame();
|
||||
std::thread::sleep(Duration::from_millis(100));
|
||||
for _ in 0..10 {
|
||||
host.service();
|
||||
std::thread::sleep(Duration::from_millis(10));
|
||||
}
|
||||
assert!(audio.ready());
|
||||
audio.stop(0);
|
||||
audio.finish_frame();
|
||||
std::thread::sleep(Duration::from_millis(100));
|
||||
for _ in 0..10 {
|
||||
host.service();
|
||||
std::thread::sleep(Duration::from_millis(10));
|
||||
}
|
||||
assert!(audio.ready());
|
||||
assert!(!host.failed.load(Ordering::Relaxed));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod reclamation_tests {
|
||||
use super::*;
|
||||
use prometeu_drivers::{Audio, MemoryBanks};
|
||||
use prometeu_hal::{AudioBridge, sample::Sample};
|
||||
|
||||
#[test]
|
||||
fn stale_delivery_moves_whole_vectors_to_service_without_changing_playback() {
|
||||
let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
|
||||
let sample = Arc::new(Sample::new(48000, vec![1000; 16]));
|
||||
let weak = Arc::downgrade(&sample);
|
||||
audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On);
|
||||
audio.finish_frame();
|
||||
let stale = audio.transport().try_take().unwrap();
|
||||
let allocation = stale.frame.as_ref().unwrap().as_ptr();
|
||||
audio.reset();
|
||||
let mut mixer = AudioMixer::new();
|
||||
mixer.apply_delivery(audio.transport().try_take().unwrap());
|
||||
let mut packet = Packet::new();
|
||||
mixer.apply_delivery_into(stale, &mut packet);
|
||||
assert_eq!(packet.batches[0].as_ref().unwrap().as_ptr(), allocation);
|
||||
assert!(weak.upgrade().is_some());
|
||||
mixer.mix(&mut [0.0; 32]);
|
||||
assert!(mixer.voices.iter().all(|voice| !voice.active));
|
||||
drop(packet); // Main/service thread, including stale command owners.
|
||||
assert!(weak.upgrade().is_none());
|
||||
}
|
||||
|
||||
type Callback = Box<dyn FnMut(&mut [f32]) + Send>;
|
||||
struct ManualStream(Arc<std::sync::Mutex<Option<Callback>>>);
|
||||
impl AudioStreamHandle for ManualStream {}
|
||||
impl Drop for ManualStream {
|
||||
fn drop(&mut self) {
|
||||
self.0.lock().unwrap().take();
|
||||
}
|
||||
}
|
||||
struct ManualRuntime(Arc<std::sync::Mutex<Option<Callback>>>);
|
||||
impl AudioRuntime for ManualRuntime {
|
||||
type Device = ();
|
||||
type Stream = ManualStream;
|
||||
fn default_output_device(&self) -> Option<()> {
|
||||
Some(())
|
||||
}
|
||||
fn build_output_stream<D, E>(
|
||||
&self,
|
||||
_: &(),
|
||||
_: &cpal::StreamConfig,
|
||||
data: D,
|
||||
_: E,
|
||||
) -> Result<ManualStream, HostAudioError>
|
||||
where
|
||||
D: FnMut(&mut [f32]) + Send + 'static,
|
||||
E: FnMut(String) + Send + 'static,
|
||||
{
|
||||
*self.0.lock().unwrap() = Some(Box::new(data));
|
||||
Ok(ManualStream(self.0.clone()))
|
||||
}
|
||||
fn play_stream(&self, _: &ManualStream) -> Result<(), HostAudioError> {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
#[test]
|
||||
fn failure_stall_and_teardown_release_callback_and_pending_owners() {
|
||||
for mode in 0..3 {
|
||||
let callbacks = Arc::new(std::sync::Mutex::new(None));
|
||||
let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
|
||||
let mut host = HostAudio::new();
|
||||
host.transport = audio.transport();
|
||||
host.init_with_runtime(&ManualRuntime(callbacks.clone())).unwrap();
|
||||
let mut owners = vec![];
|
||||
for _ in 0..2 {
|
||||
let sample = Arc::new(Sample::new(48000, vec![1000; 16]));
|
||||
owners.push(Arc::downgrade(&sample));
|
||||
audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On);
|
||||
audio.finish_frame();
|
||||
callbacks.lock().unwrap().as_mut().unwrap()(&mut []);
|
||||
}
|
||||
let sample = Arc::new(Sample::new(48000, vec![1000; 16]));
|
||||
owners.push(Arc::downgrade(&sample));
|
||||
audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On);
|
||||
audio.finish_frame();
|
||||
assert!(!audio.ready());
|
||||
if mode == 0 {
|
||||
host.failed.store(true, Ordering::Relaxed);
|
||||
}
|
||||
if mode == 1 {
|
||||
host.last_progress = Instant::now() - Duration::from_secs(3);
|
||||
host.last_heartbeat = host.heartbeat.load(Ordering::Relaxed);
|
||||
}
|
||||
if mode < 2 {
|
||||
host.service();
|
||||
assert!(host._stream.is_none());
|
||||
}
|
||||
drop(host);
|
||||
assert!(audio.ready());
|
||||
assert!(callbacks.lock().unwrap().is_none());
|
||||
assert!(owners.iter().all(|owner| owner.upgrade().is_none()));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
//! Two packets circulate free -> callback -> returned -> service -> free.
|
||||
//! While the callback owns a packet, at most one packet can occupy the return
|
||||
//! lane, so its capacity-two enqueue cannot fail. Neither lane grows.
|
||||
use prometeu_drivers::{AudioCommand, AudioTransport, MAX_CHANNELS, MAX_COMMANDS_PER_FRAME};
|
||||
use prometeu_hal::sample::Sample;
|
||||
use ringbuf::{
|
||||
HeapRb,
|
||||
traits::{Consumer, Producer, Split},
|
||||
wrap::{CachingCons, CachingProd},
|
||||
};
|
||||
use std::sync::Arc;
|
||||
|
||||
pub(super) const RETIRED_CAPACITY: usize = 3 * MAX_COMMANDS_PER_FRAME + MAX_CHANNELS;
|
||||
pub(super) struct Packet {
|
||||
retired: Vec<Arc<Sample>>,
|
||||
pub batches: [Option<Vec<AudioCommand>>; 2],
|
||||
}
|
||||
impl Packet {
|
||||
pub(super) fn new() -> Self {
|
||||
Self { retired: Vec::with_capacity(RETIRED_CAPACITY), batches: [None, None] }
|
||||
}
|
||||
pub(super) fn retire(&mut self, sample: Option<Arc<Sample>>) {
|
||||
if let Some(sample) = sample {
|
||||
// Every owner comes from at most 3072 Play commands or 16 slots.
|
||||
assert!(self.retired.len() < RETIRED_CAPACITY, "audio retirement bound");
|
||||
self.retired.push(sample);
|
||||
}
|
||||
}
|
||||
fn recycle(&mut self, transport: &AudioTransport) {
|
||||
self.retired.clear();
|
||||
for batch in &mut self.batches {
|
||||
if let Some(batch) = batch.take() {
|
||||
transport.recycle_commands(batch);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
type Prod = CachingProd<Arc<HeapRb<Packet>>>;
|
||||
type Cons = CachingCons<Arc<HeapRb<Packet>>>;
|
||||
pub(super) struct CallbackLane {
|
||||
free: Cons,
|
||||
returned: Prod,
|
||||
}
|
||||
/// Main-thread endpoint. Service independently of guest progress or pause.
|
||||
pub struct AudioReclaimer {
|
||||
free: Prod,
|
||||
returned: Cons,
|
||||
}
|
||||
pub(super) fn pool() -> (CallbackLane, AudioReclaimer) {
|
||||
let (mut free, free_cons) = HeapRb::new(2).split();
|
||||
let (returned, returned_cons) = HeapRb::new(2).split();
|
||||
for _ in 0..2 {
|
||||
assert!(free.try_push(Packet::new()).is_ok());
|
||||
}
|
||||
(CallbackLane { free: free_cons, returned }, AudioReclaimer { free, returned: returned_cons })
|
||||
}
|
||||
impl CallbackLane {
|
||||
pub(super) fn take(&mut self) -> Option<Packet> {
|
||||
self.free.try_pop()
|
||||
}
|
||||
pub(super) fn give_back(&mut self, packet: Packet) {
|
||||
// Conservation proves capacity; there is no overflow/drop fallback.
|
||||
assert!(self.returned.try_push(packet).is_ok(), "audio packet conservation");
|
||||
}
|
||||
}
|
||||
impl AudioReclaimer {
|
||||
pub fn service(&mut self, transport: &AudioTransport) {
|
||||
while let Some(mut packet) = self.returned.try_pop() {
|
||||
packet.recycle(transport);
|
||||
assert!(self.free.try_push(packet).is_ok(), "audio packet conservation");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
#[test]
|
||||
fn two_packets_conserve_capacity_across_service_starvation() {
|
||||
let (mut callback, mut service) = pool();
|
||||
let first = callback.take().unwrap();
|
||||
let second = callback.take().unwrap();
|
||||
assert!(callback.take().is_none());
|
||||
callback.give_back(first);
|
||||
callback.give_back(second);
|
||||
assert!(callback.take().is_none());
|
||||
let transport = AudioTransport::default();
|
||||
for _ in 0..1000 {
|
||||
service.service(&transport);
|
||||
for _ in 0..2 {
|
||||
let packet = callback.take().unwrap();
|
||||
assert_eq!(packet.retired.capacity(), RETIRED_CAPACITY);
|
||||
assert!(packet.retired.is_empty());
|
||||
assert!(packet.batches.iter().all(Option::is_none));
|
||||
callback.give_back(packet);
|
||||
}
|
||||
assert!(callback.take().is_none());
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -433,6 +433,9 @@ impl ApplicationHandler for HostRunner {
|
||||
|
||||
// Consume time in exact 60Hz slices.
|
||||
while self.accumulator >= self.frame_target_dt {
|
||||
// Reclaim returned audio owners before another guest attempt, even
|
||||
// when the previous attempt paused or stopped at backpressure.
|
||||
self.audio.service();
|
||||
// Unless the debugger is waiting for a 'start' command, advance the system.
|
||||
if !self.debugger.waiting_for_start {
|
||||
self.firmware.tick(&self.input.signals, &mut self.hardware);
|
||||
|
||||
@@ -0,0 +1,347 @@
|
||||
use prometeu_drivers::{Audio, MemoryBanks};
|
||||
use prometeu_hal::{AudioBridge, LoopMode, sample::Sample};
|
||||
use prometeu_host_desktop_winit::audio::AudioCallback;
|
||||
use std::alloc::{GlobalAlloc, Layout, System};
|
||||
use std::cell::Cell;
|
||||
use std::sync::Arc;
|
||||
|
||||
thread_local! {
|
||||
static COUNTS: Cell<Option<(usize, usize)>> = const { Cell::new(None) };
|
||||
}
|
||||
struct Counter;
|
||||
fn count(alloc: usize, free: usize) {
|
||||
let _ = COUNTS.try_with(|c| {
|
||||
if let Some((a, d)) = c.get() {
|
||||
c.set(Some((a + alloc, d + free)));
|
||||
}
|
||||
});
|
||||
}
|
||||
unsafe impl GlobalAlloc for Counter {
|
||||
unsafe fn alloc(&self, l: Layout) -> *mut u8 {
|
||||
count(1, 0);
|
||||
unsafe { System.alloc(l) }
|
||||
}
|
||||
unsafe fn alloc_zeroed(&self, l: Layout) -> *mut u8 {
|
||||
count(1, 0);
|
||||
unsafe { System.alloc_zeroed(l) }
|
||||
}
|
||||
unsafe fn dealloc(&self, p: *mut u8, l: Layout) {
|
||||
count(0, 1);
|
||||
unsafe { System.dealloc(p, l) }
|
||||
}
|
||||
unsafe fn realloc(&self, p: *mut u8, l: Layout, n: usize) -> *mut u8 {
|
||||
count(1, 1);
|
||||
unsafe { System.realloc(p, l, n) }
|
||||
}
|
||||
}
|
||||
#[global_allocator]
|
||||
static ALLOCATOR: Counter = Counter;
|
||||
|
||||
fn measured(f: impl FnOnce()) -> (usize, usize) {
|
||||
COUNTS.with(|c| c.set(Some((0, 0))));
|
||||
f();
|
||||
COUNTS.with(|c| c.replace(None).unwrap())
|
||||
}
|
||||
|
||||
fn play(audio: &mut Audio, voice: usize, looping: bool) -> std::sync::Weak<Sample> {
|
||||
let sample = Arc::new(Sample::new(48000, vec![1000; 4]));
|
||||
let weak = Arc::downgrade(&sample);
|
||||
assert_eq!(
|
||||
audio.play_sample(
|
||||
sample,
|
||||
voice,
|
||||
255,
|
||||
0,
|
||||
1.0,
|
||||
0,
|
||||
if looping { LoopMode::On } else { LoopMode::Off }
|
||||
),
|
||||
prometeu_hal::AudioOpStatus::Ok
|
||||
);
|
||||
weak
|
||||
}
|
||||
fn render(callback: &mut AudioCallback, audio: &Audio, pcm: &mut [f32], label: &str) {
|
||||
let counts = measured(|| callback.render(&audio.transport(), pcm));
|
||||
println!("{label}: {counts:?}");
|
||||
assert_eq!(counts, (0, 0), "{label}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn callback_owners_do_not_use_allocator() {
|
||||
let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
|
||||
let (mut callback, mut reclaimer) = AudioCallback::new();
|
||||
let mut pcm = [0.0; 32];
|
||||
let weak = play(&mut audio, 0, false);
|
||||
audio.finish_frame();
|
||||
render(&mut callback, &audio, &mut pcm, "natural_completion_and_batch");
|
||||
assert!(weak.upgrade().is_some(), "owner must await service");
|
||||
reclaimer.service(&audio.transport());
|
||||
assert!(weak.upgrade().is_none());
|
||||
for _ in 0..8 {
|
||||
play(&mut audio, 0, true);
|
||||
audio.stop(0);
|
||||
let replacement = play(&mut audio, 0, true);
|
||||
audio.finish_frame();
|
||||
render(&mut callback, &audio, &mut pcm, "replacement_stop_fifo");
|
||||
assert!(pcm.iter().step_by(2).all(|&v| v == 1000.0 / 32768.0));
|
||||
reclaimer.service(&audio.transport());
|
||||
audio.set_paused(true);
|
||||
render(&mut callback, &audio, &mut pcm, "pause");
|
||||
assert!(pcm.iter().all(|&v| v == 0.0));
|
||||
reclaimer.service(&audio.transport());
|
||||
audio.reset();
|
||||
render(&mut callback, &audio, &mut pcm, "epoch_reset");
|
||||
assert!(replacement.upgrade().is_some());
|
||||
reclaimer.service(&audio.transport());
|
||||
assert!(replacement.upgrade().is_none());
|
||||
}
|
||||
audio.stop(0);
|
||||
audio.finish_frame();
|
||||
render(&mut callback, &audio, &mut pcm, "control_batch");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn stalled_service_bounds_retention_and_recovers_pending_delivery() {
|
||||
let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
|
||||
let (mut callback, mut reclaimer) = AudioCallback::new();
|
||||
let owners: Vec<_> = (0..16).map(|voice| play(&mut audio, voice, false)).collect();
|
||||
audio.finish_frame();
|
||||
// Keep all voices playing until both packets have been returned.
|
||||
render(&mut callback, &audio, &mut [], "start_16");
|
||||
render(&mut callback, &audio, &mut [], "exhaust_pool");
|
||||
let mut pcm = [0.0; 32];
|
||||
render(&mut callback, &audio, &mut pcm, "finish_16_without_packet");
|
||||
assert!(owners.iter().all(|owner| owner.upgrade().is_some()));
|
||||
let next = play(&mut audio, 0, true);
|
||||
audio.finish_frame();
|
||||
for _ in 0..10 {
|
||||
render(&mut callback, &audio, &mut pcm, "starved_silent_pending");
|
||||
assert!(!audio.ready());
|
||||
assert!(pcm.iter().all(|&v| v == 0.0));
|
||||
}
|
||||
reclaimer.service(&audio.transport());
|
||||
render(&mut callback, &audio, &mut pcm, "recover");
|
||||
assert!(audio.ready());
|
||||
reclaimer.service(&audio.transport());
|
||||
assert!(owners.iter().all(|owner| owner.upgrade().is_none()));
|
||||
assert!(next.upgrade().is_some());
|
||||
drop(callback); // Teardown belongs to the service/main thread.
|
||||
drop(reclaimer);
|
||||
assert!(next.upgrade().is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn full_frame_and_combined_lifecycle_fit_one_packet() {
|
||||
let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
|
||||
let (mut callback, mut reclaimer) = AudioCallback::new();
|
||||
let mut owners = Vec::new();
|
||||
for voice in 0..16 {
|
||||
owners.push(play(&mut audio, voice, false));
|
||||
}
|
||||
audio.finish_frame();
|
||||
render(&mut callback, &audio, &mut [], "initial_16");
|
||||
reclaimer.service(&audio.transport());
|
||||
// The published frame, interrupted next-frame prefix and lifecycle each
|
||||
// admit 1024 commands. Every command replaces an owner on the same voice.
|
||||
for _ in 0..1024 {
|
||||
owners.push(play(&mut audio, 0, false));
|
||||
}
|
||||
audio.finish_frame();
|
||||
for _ in 0..1024 {
|
||||
owners.push(play(&mut audio, 0, false));
|
||||
}
|
||||
audio.begin_lifecycle();
|
||||
for _ in 0..1024 {
|
||||
owners.push(play(&mut audio, 0, false));
|
||||
}
|
||||
audio.finish_lifecycle(true);
|
||||
let mut pcm = [0.0; 32];
|
||||
render(&mut callback, &audio, &mut pcm, "3072_commands_plus_completion");
|
||||
reclaimer.service(&audio.transport());
|
||||
assert!(owners.iter().skip(16).all(|owner| owner.upgrade().is_none()));
|
||||
audio.reset();
|
||||
render(&mut callback, &audio, &mut pcm, "reset_remaining_voices");
|
||||
reclaimer.service(&audio.transport());
|
||||
assert!(owners.iter().all(|owner| owner.upgrade().is_none()));
|
||||
}
|
||||
|
||||
/// Physical observations, deliberately excluded from ordinary CI. The pressure
|
||||
/// fixture reads the checked-in asset pack and writes a temporary host save;
|
||||
/// it does not certify asset decoding or guest memcard scheduling.
|
||||
#[test]
|
||||
#[ignore = "requires physical audio output; 16 quiet voices and temporary file I/O"]
|
||||
fn physical_callback_duration_16_voices_with_io_pressure() {
|
||||
use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
|
||||
use prometeu_host_desktop_winit::fs_backend::HostDirBackend;
|
||||
use prometeu_system::fs::FsBackend;
|
||||
use ringbuf::{
|
||||
HeapRb,
|
||||
traits::{Consumer, Producer, Split},
|
||||
};
|
||||
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
|
||||
use std::time::{Duration, Instant};
|
||||
let device = cpal::default_host().default_output_device().expect("physical output");
|
||||
let device_name = device.name().unwrap();
|
||||
let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
|
||||
let (mut callback, mut reclaimer) = AudioCallback::new();
|
||||
let mut owners = vec![];
|
||||
for voice in 0..16 {
|
||||
let sample = Arc::new(Sample::new(48000, vec![32; 4800]));
|
||||
owners.push(Arc::downgrade(&sample));
|
||||
audio.play_sample(sample, voice, 8, 127, 1.0, 0, LoopMode::On);
|
||||
}
|
||||
audio.finish_frame();
|
||||
let config = cpal::StreamConfig {
|
||||
channels: 2,
|
||||
sample_rate: cpal::SampleRate(48000),
|
||||
buffer_size: cpal::BufferSize::Fixed(256),
|
||||
};
|
||||
let transport = audio.transport();
|
||||
let (mut timings, mut observations) = HeapRb::<(u64, usize)>::new(4096).split();
|
||||
let allocator_calls = Arc::new(AtomicUsize::new(0));
|
||||
let failed = Arc::new(AtomicBool::new(false));
|
||||
let counter = allocator_calls.clone();
|
||||
let error = failed.clone();
|
||||
let stream = device
|
||||
.build_output_stream(
|
||||
&config,
|
||||
move |data: &mut [f32], _: &cpal::OutputCallbackInfo| {
|
||||
let start = Instant::now();
|
||||
let (alloc, free) = measured(|| callback.render(&transport, data));
|
||||
counter.fetch_add(alloc + free, Ordering::Relaxed);
|
||||
let _ = timings.try_push((start.elapsed().as_nanos() as u64, data.len() / 2));
|
||||
},
|
||||
move |_| {
|
||||
error.store(true, Ordering::Relaxed);
|
||||
},
|
||||
None,
|
||||
)
|
||||
.unwrap();
|
||||
let root =
|
||||
std::env::temp_dir().join(format!("prometeu-audio-qualification-{}", std::process::id()));
|
||||
std::fs::create_dir_all(&root).unwrap();
|
||||
let mut filesystem = HostDirBackend::new(root.clone());
|
||||
let asset = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("../../../test-cartridges/stress-console/assets.pa");
|
||||
let save = vec![0x5a; 1024 * 1024];
|
||||
stream.play().unwrap();
|
||||
let deadline = Instant::now() + Duration::from_secs(2);
|
||||
let mut io_cycles = 0;
|
||||
while Instant::now() < deadline {
|
||||
let payload = std::fs::read(&asset).unwrap();
|
||||
assert!(!payload.is_empty());
|
||||
filesystem.write_file("/user/audio-pressure.bin", &save).unwrap();
|
||||
reclaimer.service(&audio.transport());
|
||||
io_cycles += 1;
|
||||
std::thread::sleep(Duration::from_millis(2));
|
||||
}
|
||||
stream.pause().unwrap();
|
||||
let live_before = owners.iter().filter(|owner| owner.upgrade().is_some()).count();
|
||||
drop(stream);
|
||||
reclaimer.service(&audio.transport());
|
||||
let live_after = owners.iter().filter(|owner| owner.upgrade().is_some()).count();
|
||||
let mut samples = vec![];
|
||||
let mut frames = vec![];
|
||||
while let Some((time, count)) = observations.try_pop() {
|
||||
samples.push(time);
|
||||
frames.push(count);
|
||||
}
|
||||
filesystem.delete("/user/audio-pressure.bin").unwrap();
|
||||
std::fs::remove_dir(root.join("user")).unwrap();
|
||||
std::fs::remove_dir(root).unwrap();
|
||||
samples.sort_unstable();
|
||||
assert!(!samples.is_empty(), "physical stream delivered no callbacks");
|
||||
println!(
|
||||
"device={device_name:?}, callbacks={}, io_cycles={io_cycles}, frames_min={}, frames_max={}, p50_ns={}, p95_ns={}, p99_ns={}, max_ns={}, allocator_calls={}, owners_before={live_before}, owners_after={live_after}",
|
||||
samples.len(),
|
||||
frames.iter().min().unwrap(),
|
||||
frames.iter().max().unwrap(),
|
||||
samples[samples.len() / 2],
|
||||
samples[samples.len() * 95 / 100],
|
||||
samples[samples.len() * 99 / 100],
|
||||
samples.last().unwrap(),
|
||||
allocator_calls.load(Ordering::Relaxed)
|
||||
);
|
||||
assert!(!failed.load(Ordering::Relaxed));
|
||||
assert_eq!(allocator_calls.load(Ordering::Relaxed), 0);
|
||||
assert_eq!((live_before, live_after), (16, 0));
|
||||
}
|
||||
|
||||
#[test]
|
||||
#[ignore = "release timing observation with temporary asset-read/save-write pressure"]
|
||||
fn callback_duration_16_voices_with_io_pressure() {
|
||||
use prometeu_host_desktop_winit::fs_backend::HostDirBackend;
|
||||
use prometeu_system::fs::FsBackend;
|
||||
use std::time::Instant;
|
||||
let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
|
||||
let (mut callback, mut reclaimer) = AudioCallback::new();
|
||||
let owners: Vec<_> = (0..16).map(|voice| play(&mut audio, voice, true)).collect();
|
||||
audio.finish_frame();
|
||||
let mut pcm = [0.0; 512]; // 256 stereo frames: nominal 5.333 ms at 48 kHz.
|
||||
callback.render(&audio.transport(), &mut pcm);
|
||||
reclaimer.service(&audio.transport());
|
||||
let root = std::env::temp_dir().join(format!("prometeu-audio-timing-{}", std::process::id()));
|
||||
std::fs::create_dir_all(&root).unwrap();
|
||||
let mut filesystem = HostDirBackend::new(root.clone());
|
||||
let asset = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("../../../test-cartridges/stress-console/assets.pa");
|
||||
let save = vec![0x5a; 1024 * 1024];
|
||||
let mut samples = Vec::with_capacity(1000);
|
||||
let mut counts = (0, 0);
|
||||
for _ in 0..1000 {
|
||||
assert!(!std::fs::read(&asset).unwrap().is_empty());
|
||||
filesystem.write_file("/user/audio-pressure.bin", &save).unwrap();
|
||||
let start = Instant::now();
|
||||
let measured = measured(|| callback.render(&audio.transport(), &mut pcm));
|
||||
samples.push(start.elapsed().as_nanos());
|
||||
counts.0 += measured.0;
|
||||
counts.1 += measured.1;
|
||||
reclaimer.service(&audio.transport());
|
||||
}
|
||||
samples.sort_unstable();
|
||||
let before = owners.iter().filter(|owner| owner.upgrade().is_some()).count();
|
||||
drop(callback);
|
||||
drop(reclaimer);
|
||||
let after = owners.iter().filter(|owner| owner.upgrade().is_some()).count();
|
||||
filesystem.delete("/user/audio-pressure.bin").unwrap();
|
||||
std::fs::remove_dir(root.join("user")).unwrap();
|
||||
std::fs::remove_dir(root).unwrap();
|
||||
println!(
|
||||
"synthetic callbacks=1000, frames=256, nominal_period_ns=5333333, io_cycles=1000, p50_ns={}, p95_ns={}, p99_ns={}, max_ns={}, alloc_free={counts:?}, owners_before={before}, owners_after={after}",
|
||||
samples[500], samples[950], samples[990], samples[999]
|
||||
);
|
||||
assert_eq!(counts, (0, 0));
|
||||
assert_eq!((before, after), (16, 0));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unloaded_banks_empty_samples_and_controls_reclaim_on_service() {
|
||||
use prometeu_drivers::SoundBankPoolInstaller;
|
||||
use prometeu_hal::sound_bank::SoundBank;
|
||||
let banks = Arc::new(MemoryBanks::new());
|
||||
let sample = Arc::new(Sample::new(48000, vec![1000; 16]));
|
||||
let weak = Arc::downgrade(&sample);
|
||||
banks.install_sound_bank(0, Arc::new(SoundBank::new(vec![sample])));
|
||||
let mut audio = Audio::new(banks.clone());
|
||||
let (mut callback, mut reclaimer) = AudioCallback::new();
|
||||
audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::On);
|
||||
audio.finish_frame();
|
||||
banks.clear_sound_banks();
|
||||
let mut pcm = [0.0; 16];
|
||||
render(&mut callback, &audio, &mut pcm, "unloaded_bank");
|
||||
assert!(weak.upgrade().is_some());
|
||||
reclaimer.service(&audio.transport());
|
||||
audio.set_volume(0, 127);
|
||||
audio.set_pan(0, 255);
|
||||
audio.set_pitch(0, 0.5);
|
||||
audio.stop(0);
|
||||
let empty = Arc::new(Sample::new(48000, vec![]));
|
||||
let weak_empty = Arc::downgrade(&empty);
|
||||
audio.play_sample(empty, 1, 255, 0, 1.0, 0, LoopMode::Off);
|
||||
audio.finish_frame();
|
||||
render(&mut callback, &audio, &mut pcm, "controls_stop_empty");
|
||||
assert!(pcm.iter().all(|&sample| sample == 0.0));
|
||||
assert!(weak.upgrade().is_some() && weak_empty.upgrade().is_some());
|
||||
reclaimer.service(&audio.transport());
|
||||
assert!(weak.upgrade().is_none() && weak_empty.upgrade().is_none());
|
||||
}
|
||||
+34
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user