From f029304cf44f384d1fd58799bcf3d3458a0e7e73 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 15 Oct 2026 03:28:39 +0200 Subject: [PATCH] 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). --- architecture.md | 12 +++++----- fader_master/src/local.rs | 16 ++++++++++--- sound/src/pulse_worker.rs | 47 ++++++++++++++++++++++++++++++++++++--- task.md | 3 ++- 4 files changed, 66 insertions(+), 12 deletions(-) diff --git a/architecture.md b/architecture.md index d089846..d0a7aaa 100644 --- a/architecture.md +++ b/architecture.md @@ -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. diff --git a/fader_master/src/local.rs b/fader_master/src/local.rs index ef9270b..4934ec6 100644 --- a/fader_master/src/local.rs +++ b/fader_master/src/local.rs @@ -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> { diff --git a/sound/src/pulse_worker.rs b/sound/src/pulse_worker.rs index 3917fc6..d05f8c6 100644 --- a/sound/src/pulse_worker.rs +++ b/sound/src/pulse_worker.rs @@ -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) -> Self { @@ -252,9 +267,21 @@ impl PulseWorker { C: PulseConnection, F: FnOnce() -> Result + 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( + epoch: BackendEpoch, + command_capacity: usize, + event_capacity: usize, + connect: F, + ) -> Self + where + C: PulseConnection, + F: FnOnce() -> Result + 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()); + } } diff --git a/task.md b/task.md index 7342981..091ab38 100644 --- a/task.md +++ b/task.md @@ -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