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
@@ -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);