1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
//! Snapshots of a chain's plugin settings, and recovering a realtime endpoint in a new helper
//! from one while the audio callback keeps the endpoint.
use plughost_core::StatePurpose;
use super::*;
/// What recovery restores of a chain's plugins, from [`Chain::snapshot`], in chain order.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct ChainSnapshot {
/// Each slot's plugin, its state saved with [`StatePurpose::Project`], its native bypass as
/// [`Chain::bypass`] reported it, or `None` where unavailable, and its host bypass.
pub slots: Vec<ChainSlot>,
}
impl Chain {
/// Saves each slot's plugin, project state, native bypass and host bypass for
/// [`Chain::recover`] and [`Chain::recover_realtime`], or for [`Chain::spawn`] in another
/// helper. It works while the realtime endpoint runs, as [`Chain::save_state`] and
/// [`Chain::bypass`] do; plughost never takes one by itself. Take
/// snapshots while the helper is well: a plugin hanging in its processing may also hold up
/// saving its state.
pub fn snapshot(&mut self) -> Result<ChainSnapshot, Error> {
let mut slots = Vec::with_capacity(self.plugins.len());
for slot in 0..self.plugins.len() {
slots.push(ChainSlot {
plugin: self.plugins[slot].clone(),
state: Some(self.save_state(slot, StatePurpose::Project)?),
bypass: self.bypass(slot)?.enabled,
host_bypass: self.host_bypass(slot)?,
});
}
Ok(ChainSnapshot { slots })
}
/// Recovers this chain's realtime endpoint in a new helper, typically after its helper
/// crashed (see [`Chain::helper_monitor`]) or hung (see
/// [`crate::RealtimeStatus::stalled`]), while the audio callback keeps the same
/// [`crate::RealtimeEndpoint`]. The endpoint plays its fallback from the call on, as in a
/// resync. A new chain of `slots`, normally the [`ChainSnapshot::slots`] of
/// [`Chain::snapshot`], is prepared as by [`Chain::recover`]. The endpoint then moves to
/// the new chain with its configuration and counters and starts again there: after `latency`
/// priming callbacks it plays the new chain's output, as after [`Chain::start_realtime`].
/// The new chain holds only what the slots hold; see [`Chain::recover`].
///
/// This chain's helper is not contacted. A hung one may go on until this chain is dropped,
/// but only with this chain's shared memory, never the new chain's. Switch to the returned
/// chain and drop this one, which no longer has the endpoint; the shared memory the endpoint
/// left is released by the new chain's [`Chain::realtime_status`] or
/// [`Chain::stop_realtime`].
///
/// Without an endpoint this returns [`Error::NotPrepared`]. On any other failure the endpoint
/// stays with this chain, playing its fallback with `resync` set, and nothing is retried: the
/// application recovers again, or stops the endpoint, resets this chain and starts it again
/// when its helper is well.
pub fn recover_realtime(&mut self, slots: &[ChainSlot]) -> Result<Chain, Error> {
let realtime = self.realtime.as_ref().ok_or(Error::NotPrepared)?;
realtime.state.suspend();
let config = realtime.config;
let mut chain = self.recover(slots)?;
let ring = chain.install_ring(&config)?;
let mut realtime = self.realtime.take().ok_or(Error::NotPrepared)?;
let control = std::mem::replace(&mut realtime.control, ring.control());
let running = std::mem::replace(&mut realtime.running, false);
// The counters go on from what this chain's ring counted.
let late = realtime.late;
realtime.late += control.worker().0;
chain.realtime = Some(realtime);
match chain.start_generation(Some(Box::new(ring))) {
Ok(_) => Ok(chain),
Err(error) => {
// The callback has not been handed the ring; the endpoint returns to this chain
// before the new one is dropped, so that dropping it does not close the endpoint.
if let Some(mut realtime) = chain.realtime.take() {
realtime.control = control;
realtime.running = running;
realtime.late = late;
self.realtime = Some(realtime);
}
Err(error)
}
}
}
}