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