plughost 0.2.2

Load and run VST3, Audio Unit, and CLAP plugins from Rust, isolated in helper processes
Documentation
//! 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`], and its native
    /// bypass as [`Chain::bypass`] reported it, or `None` where unavailable.
    pub slots: Vec<ChainSlot>,
}

impl Chain {
    /// Saves each slot's plugin, project state and native 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,
            });
        }
        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)
            }
        }
    }
}