plughost-core 0.2.6

Shared types and offline render rules for plughost
Documentation
use std::collections::VecDeque;
use std::sync::{Arc, Mutex};

/// Maximum queued parameter notifications. Past it the oldest record is dropped, but not a
/// metadata change.
pub const PARAMETER_EVENT_CAPACITY: usize = 256;

/// Notifications reported by the plugin, in observed order, but for two merges: a value reported
/// for an ID replaces the one queued for it when no gesture of that ID or metadata change came
/// between them, and a values change replaces the one queued before it. Values are normalized to
/// 0..=1.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub enum ParameterEvent {
    /// A parameter’s normalized value changed.
    Value {
        /// Native parameter ID or Audio Unit address.
        id: u64,
        /// Finite normalized value in `0..=1`.
        normalized: f64,
    },
    /// A native parameter edit gesture began.
    BeginEdit {
        /// Native parameter ID or Audio Unit address.
        id: u64,
    },
    /// A native parameter edit gesture ended.
    EndEdit {
        /// Native parameter ID or Audio Unit address.
        id: u64,
    },
    /// Parameter metadata should be queried again.
    MetadataChanged,
    /// Current parameter values should be queried again.
    ValuesChanged,
    /// The plugin reported its persistent state’s dirty status.
    Dirty {
        /// Whether the plugin reports unsaved changes.
        dirty: bool,
    },
}

/// Overflow loses ordering continuity: cancel open gestures and requery metadata and values.
#[derive(Clone, Debug, Default, PartialEq)]
#[non_exhaustive]
#[must_use]
pub struct ParameterEventBatch {
    /// Notifications retained in observed order, merged as [`ParameterEvent`] says.
    pub events: Vec<ParameterEvent>,
    /// Cancel open gestures and requery metadata and values when true.
    pub resync_required: bool,
    /// Number of lost records since the previous drain, including upstream loss.
    pub dropped: u64,
}

impl ParameterEventBatch {
    /// Each field as given. Internal to the plughost crates; exempt from semver.
    #[doc(hidden)]
    pub fn new(
        events: Vec<ParameterEvent>,
        resync_required: bool,
        dropped: u64,
    ) -> ParameterEventBatch {
        ParameterEventBatch {
            events,
            resync_required,
            dropped,
        }
    }
}

struct Pending {
    events: VecDeque<ParameterEvent>,
    dropped: u64,
    resync_required: bool,
}

impl Default for Pending {
    fn default() -> Self {
        Self {
            events: VecDeque::with_capacity(PARAMETER_EVENT_CAPACITY),
            dropped: 0,
            resync_required: false,
        }
    }
}

impl Pending {
    /// Appends `event`. A full queue drops its oldest record, but not a metadata change: the
    /// helper refreshes metadata only when one is there, so it outlives the values a flood drops.
    /// A metadata change already queued stands for another. A values change replaces the one
    /// queued before it: the values are read again after every record before it.
    fn push(&mut self, event: ParameterEvent) {
        match event {
            ParameterEvent::MetadataChanged if self.events.contains(&event) => return,
            ParameterEvent::ValuesChanged => self.events.retain(|queued| *queued != event),
            _ => {}
        }
        if self.events.len() == PARAMETER_EVENT_CAPACITY {
            // At most one metadata change is queued, so the oldest other record is the first or
            // the second.
            let oldest = usize::from(self.events[0] == ParameterEvent::MetadataChanged);
            self.events.remove(oldest);
            self.dropped = self.dropped.saturating_add(1);
        }
        self.events.push_back(event);
    }
}

/// A bounded producer queue shared by native callbacks and the owning main thread.
#[derive(Clone, Default)]
pub struct ParameterEventBuffer(Arc<Mutex<Pending>>);

impl ParameterEventBuffer {
    /// Merges a producer batch without hiding loss already reported by that producer.
    pub fn append(&self, batch: ParameterEventBatch) {
        let mut pending = self.0.lock().unwrap_or_else(|error| error.into_inner());
        pending.dropped = pending.dropped.saturating_add(batch.dropped);
        pending.resync_required |= batch.resync_required;
        for event in batch.events {
            pending.push(event);
        }
    }

    /// Appends one notification, dropping the oldest on capacity overflow.
    pub fn record(&self, event: ParameterEvent) {
        let mut pending = self.0.lock().unwrap_or_else(|error| error.into_inner());
        pending.push(event);
    }

    /// Records a value the plugin reported for `id`, replacing the one queued for it when no
    /// gesture of `id` or metadata change came after: a meter that reports every block takes one
    /// record until the queue is drained, not one per block.
    pub fn record_value(&self, id: u64, normalized: f64) {
        let mut pending = self.0.lock().unwrap_or_else(|error| error.into_inner());
        let last = pending.events.iter_mut().rev().find(|event| {
            matches!(event,
                ParameterEvent::Value { id: other, .. }
                | ParameterEvent::BeginEdit { id: other }
                | ParameterEvent::EndEdit { id: other } if *other == id)
                || **event == ParameterEvent::MetadataChanged
        });
        if let Some(ParameterEvent::Value {
            normalized: queued, ..
        }) = last
        {
            *queued = normalized;
            return;
        }
        pending.push(ParameterEvent::Value { id, normalized });
    }

    /// Drains notifications and loss counters into an owned batch.
    pub fn take(&self) -> ParameterEventBatch {
        let mut pending = self.0.lock().unwrap_or_else(|error| error.into_inner());
        let dropped = std::mem::take(&mut pending.dropped);
        ParameterEventBatch {
            events: pending.events.drain(..).collect(),
            resync_required: std::mem::take(&mut pending.resync_required) || dropped != 0,
            dropped,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn shared_queue_preserves_gestures_and_reports_lost_continuity() {
        let consumer = ParameterEventBuffer::default();
        let producer = consumer.clone();
        producer.record(ParameterEvent::BeginEdit { id: 3 });
        for id in 0..PARAMETER_EVENT_CAPACITY as u64 {
            producer.record(ParameterEvent::Value {
                id,
                normalized: 0.5,
            });
        }
        producer.record(ParameterEvent::EndEdit { id: 3 });
        let batch = consumer.take();
        assert_eq!(batch.events.len(), PARAMETER_EVENT_CAPACITY);
        assert_eq!(batch.dropped, 2);
        assert!(batch.resync_required);
        assert_eq!(
            batch.events.first(),
            Some(&ParameterEvent::Value {
                id: 1,
                normalized: 0.5
            })
        );
        assert_eq!(
            batch.events.last(),
            Some(&ParameterEvent::EndEdit { id: 3 })
        );
        assert_eq!(consumer.take(), ParameterEventBatch::default());
    }

    #[test]
    fn appending_preserves_upstream_loss_and_requery_requests() {
        let buffer = ParameterEventBuffer::default();
        buffer.append(ParameterEventBatch {
            events: vec![ParameterEvent::MetadataChanged],
            dropped: 4,
            resync_required: true,
        });
        buffer.append(ParameterEventBatch {
            events: vec![ParameterEvent::ValuesChanged],
            dropped: 0,
            resync_required: false,
        });
        let batch = buffer.take();
        assert_eq!(
            batch.events,
            vec![
                ParameterEvent::MetadataChanged,
                ParameterEvent::ValuesChanged
            ]
        );
        assert_eq!(batch.dropped, 4);
        assert!(batch.resync_required);
        buffer.append(ParameterEventBatch {
            events: Vec::new(),
            dropped: 0,
            resync_required: true,
        });
        assert!(buffer.take().resync_required);
    }

    #[test]
    fn a_metadata_change_outlives_a_flood_of_values() {
        let buffer = ParameterEventBuffer::default();
        buffer.record(ParameterEvent::MetadataChanged);
        for id in 0..2 * PARAMETER_EVENT_CAPACITY as u64 {
            buffer.record(ParameterEvent::Value {
                id,
                normalized: 0.5,
            });
        }
        buffer.record(ParameterEvent::MetadataChanged);
        let batch = buffer.take();
        assert_eq!(batch.events.len(), PARAMETER_EVENT_CAPACITY);
        assert_eq!(batch.events[0], ParameterEvent::MetadataChanged);
        assert_eq!(
            batch
                .events
                .iter()
                .filter(|event| **event == ParameterEvent::MetadataChanged)
                .count(),
            1
        );
        assert!(batch.resync_required);
    }

    #[test]
    fn reported_values_replace_the_queued_one_up_to_a_gesture() {
        let buffer = ParameterEventBuffer::default();
        for normalized in [0.1, 0.2, 0.3] {
            buffer.record_value(7, normalized);
            buffer.record_value(8, normalized);
        }
        buffer.record(ParameterEvent::BeginEdit { id: 7 });
        buffer.record_value(7, 0.4);
        buffer.record_value(7, 0.5);
        let value = |id, normalized| ParameterEvent::Value { id, normalized };
        assert_eq!(
            buffer.take().events,
            [
                value(7, 0.3),
                value(8, 0.3),
                ParameterEvent::BeginEdit { id: 7 },
                value(7, 0.5)
            ]
        );
    }

    #[test]
    fn a_value_is_not_merged_across_a_metadata_change() {
        let buffer = ParameterEventBuffer::default();
        let value = |id, normalized| ParameterEvent::Value { id, normalized };
        buffer.record_value(7, 0.1);
        buffer.record(ParameterEvent::MetadataChanged);
        buffer.record_value(7, 0.2);
        assert_eq!(
            buffer.take().events,
            [
                value(7, 0.1),
                ParameterEvent::MetadataChanged,
                value(7, 0.2)
            ]
        );
    }

    #[test]
    fn a_values_change_replaces_the_one_queued_before_it() {
        let buffer = ParameterEventBuffer::default();
        buffer.record(ParameterEvent::BeginEdit { id: 7 });
        for _ in 0..2 * PARAMETER_EVENT_CAPACITY {
            buffer.record_value(7, 0.5);
            buffer.record_value(8, 0.5);
            buffer.record(ParameterEvent::ValuesChanged);
        }
        buffer.record_value(7, 0.6);
        let batch = buffer.take();
        let value = |id, normalized| ParameterEvent::Value { id, normalized };
        assert_eq!(
            batch.events,
            [
                ParameterEvent::BeginEdit { id: 7 },
                value(7, 0.6),
                value(8, 0.5),
                ParameterEvent::ValuesChanged
            ]
        );
        assert_eq!(batch.dropped, 0);
    }
}