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