fix(M7.4): preserve Pulse snapshot capacity

Separate the one-slot worker command lane from the 256-event snapshot lane so command backpressure cannot overflow startup metadata. Report event overflow distinctly and cover one-slot command startup with a regression test.\n\nLive verification: PipeWire-Pulse server reached status=ready with Browser, Media, Master, and APC MINI snapshots.\n\nTests: cargo fmt --all -- --check; cargo check --workspace --all-targets --all-features; cargo test --workspace --all-targets --all-features; cargo test --workspace --doc --all-features; cargo clippy --workspace --all-targets --all-features -- -D warnings; cargo build --workspace --release --all-features; volume_lib no-default and pulse feature checks (all pass).
This commit is contained in:
Dandaedre 2026-10-15 03:28:39 +02:00
parent f673b313a7
commit f029304cf4
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 66 additions and 12 deletions

View File

@ -166,11 +166,13 @@ PulseAudio and native PipeWire event loops run on their own owner threads. In pa
Use bounded `mpsc` for ordered work and `watch` for latest display snapshots. Keep button edges and lifecycle events separate from coalescible fader motion. A MIDI callback only parses/copies bounded input and tries to enqueue; on overflow set an explicit fault/resync flag rather than silently losing mute edges. A dropped button edge cannot be reconstructed from an audio snapshot: report the fault and require a new user press, never guess a toggle. Dedicate output workers to rate-limited MIDI feedback. [Tokio synchronization primitives](https://docs.rs/tokio/latest/tokio/sync/index.html)
The production audio dispatcher retains a bounded server-owned queue in front
of a one-slot native worker lane. Replace unsent volume commands for the same
stream with their newest value and explicitly supersede the older operation;
never coalesce mute edges. A full non-coalescible queue is a visible fault, not
permission to drop an action. Drain copied worker events in batches so native
round-trip latency cannot starve MIDI input or local clients.
of a one-slot native worker **command** lane. Its independent event lane remains
large enough for a complete startup snapshot; command backpressure must never
shrink snapshot capacity. Replace unsent volume commands for the same stream
with their newest value and explicitly supersede the older operation; never
coalesce mute edges. A full non-coalescible queue or event lane is a visible
fault, not permission to drop an action. Drain copied worker events in batches
so native round-trip latency cannot starve MIDI input or local clients.
On shutdown stop accepting commands, stop callbacks, drain with deadlines, checkpoint confirmed state, close native connections, and join workers. Reconnect with bounded exponential backoff and cancellation; resnapshot before accepting writes. Keep other surfaces working when one disconnects. Stale backend/config generations cannot update current state.

View File

@ -51,6 +51,8 @@ pub enum LocalError {
DispatchOverflow,
#[error("audio worker event lane disconnected")]
WorkerDisconnected,
#[error("audio worker event lane overflowed; a fresh backend snapshot is required")]
WorkerEventOverflow,
#[error("MIDI runtime configuration failed: {0}")]
MidiRuntime(String),
#[error("MIDI input sequence exhausted")]
@ -188,7 +190,7 @@ impl LocalServer {
listener: OwnedListener::bind(socket)?,
// One waiting native command keeps round-trip backpressure at the
// state-owner boundary, where unsent volume motion can coalesce.
worker: PulseWorker::spawn(BackendEpoch::new(1), 1),
worker: PulseWorker::spawn_with_capacities(BackendEpoch::new(1), 1, 256),
mixer: LiveMixerState::new(write_ceiling, "pulse", profile)?,
midi,
midi_sequence: 1,
@ -221,7 +223,7 @@ impl LocalServer {
self.enqueue(commands)?;
}
Err(RecvTimeoutError::Timeout) => {}
Err(RecvTimeoutError::Disconnected) => return Err(LocalError::WorkerDisconnected),
Err(RecvTimeoutError::Disconnected) => return Err(self.worker_stop_error()),
}
loop {
match self.worker.try_receive() {
@ -231,7 +233,7 @@ impl LocalServer {
}
Err(std::sync::mpsc::TryRecvError::Empty) => break,
Err(std::sync::mpsc::TryRecvError::Disconnected) => {
return Err(LocalError::WorkerDisconnected);
return Err(self.worker_stop_error());
}
}
}
@ -309,6 +311,14 @@ impl LocalServer {
let _ = self.dispatch.pop();
}
}
fn worker_stop_error(&self) -> LocalError {
if self.worker.event_overflowed() {
LocalError::WorkerEventOverflow
} else {
LocalError::WorkerDisconnected
}
}
}
fn validate_peer(stream: &UnixStream) -> Result<(), LocalError> {

View File

@ -239,6 +239,21 @@ impl PulseWorker {
Self::spawn_to(epoch, capacity, None)
}
/// Starts a worker with independent bounded command and event lanes.
///
/// A small command lane enables upstream coalescing without constraining
/// the burst of metadata and observations emitted by an initial snapshot.
#[must_use]
pub fn spawn_with_capacities(
epoch: BackendEpoch,
command_capacity: usize,
event_capacity: usize,
) -> Self {
Self::spawn_connected_with_capacities(epoch, command_capacity, event_capacity, || {
PulseClient::connect()
})
}
/// Starts a worker against an explicit server, primarily for isolated fixtures.
#[must_use]
pub fn spawn_to(epoch: BackendEpoch, capacity: usize, server: Option<String>) -> Self {
@ -252,9 +267,21 @@ impl PulseWorker {
C: PulseConnection,
F: FnOnce() -> Result<C, PulseError> + Send + 'static,
{
let capacity = capacity.max(1);
let (command_sender, command_receiver) = mpsc::sync_channel(capacity);
let (event_sender, event_receiver) = mpsc::sync_channel(capacity);
Self::spawn_connected_with_capacities(epoch, capacity, capacity, connect)
}
fn spawn_connected_with_capacities<C, F>(
epoch: BackendEpoch,
command_capacity: usize,
event_capacity: usize,
connect: F,
) -> Self
where
C: PulseConnection,
F: FnOnce() -> Result<C, PulseError> + Send + 'static,
{
let (command_sender, command_receiver) = mpsc::sync_channel(command_capacity.max(1));
let (event_sender, event_receiver) = mpsc::sync_channel(event_capacity.max(1));
let overflowed = Arc::new(AtomicBool::new(false));
let worker_overflowed = Arc::clone(&overflowed);
let thread = thread::spawn(move || {
@ -1080,4 +1107,18 @@ mod tests {
assert!(worker.shutdown());
assert!(worker.event_overflowed());
}
#[test]
fn one_slot_command_backpressure_keeps_a_full_snapshot_event_lane() {
let (connection, _, _) = FakeConnection::new(vec![stream(1, &[0.2], Mute::Unmuted)]);
let mut worker =
PulseWorker::spawn_connected_with_capacities(BackendEpoch::new(11), 1, 16, move || {
Ok(connection)
});
let events = initial_snapshot(&worker);
assert!(events.len() > 2);
assert!(!worker.event_overflowed());
assert!(worker.shutdown());
}
}

View File

@ -247,7 +247,8 @@ Dependencies: M3, M2; may proceed after the fake-adapter slice.
A joined TUI client thread owns IPC, publishes optimistic shared snapshots,
polls at 20 ms while pending and 250 ms while idle, and retains a bounded
128-edge mute FIFO. The live server uses the tested 256-command coalescing
queue ahead of a one-slot Pulse lane and drains ready worker events in batches.
queue ahead of a one-slot Pulse command lane, an independent 256-event
snapshot lane, and a batch event drain.
## M8 — Live TUI