wavecraft_dev_server/audio/

atomic_params.rs

//! Lock-free parameter bridge for audio thread access.
//!
//! Provides `AtomicParameterBridge` — a collection of `AtomicF32` values keyed
//! by parameter ID. The WebSocket thread writes parameter updates via `store()`,
//! and the audio thread reads them via `load()` with zero allocations and zero
//! locks. Relaxed ordering is sufficient because parameter updates are not
//! synchronization points; a one-block delay in propagation is acceptable.

use atomic_float::AtomicF32;
use std::collections::HashMap;
use std::sync::Arc;
use std::sync::atomic::Ordering;
use wavecraft_protocol::ParameterInfo;

// Dev-mode correctness first: use SeqCst to minimize visibility surprises
// across callback and websocket threads while debugging parameter propagation.
const PARAM_ORDERING: Ordering = Ordering::SeqCst;

/// Lock-free bridge for passing parameter values from the WebSocket thread
/// to the audio thread.
///
/// Constructed once at startup with one `Arc<AtomicF32>` per parameter. The
/// inner `HashMap` is never mutated after construction — only the atomic
/// values change. This makes reads fully lock-free and real-time safe.
pub struct AtomicParameterBridge {
    params: HashMap<String, Arc<AtomicF32>>,
    ordered_params: Vec<Arc<AtomicF32>>,
}

impl AtomicParameterBridge {
    /// Create a new bridge from parameter metadata.
    ///
    /// Each parameter gets an `AtomicF32` initialized to its default value.
    pub fn new(parameters: &[ParameterInfo]) -> Self {
        let mut params = HashMap::with_capacity(parameters.len());
        let mut ordered_params = Vec::with_capacity(parameters.len());

        for parameter in parameters {
            let atomic = Arc::new(AtomicF32::new(parameter.default));
            params.insert(parameter.id.clone(), Arc::clone(&atomic));
            ordered_params.push(atomic);
        }

        Self {
            params,
            ordered_params,
        }
    }

    /// Returns the dense plain-value parameter count in generation order.
    pub fn parameter_count(&self) -> usize {
        self.ordered_params.len()
    }

    /// Write a parameter value (called from WebSocket thread).
    ///
    /// Uses `Ordering::Relaxed` — no synchronization guarantee beyond
    /// eventual visibility. The audio thread will see the update at the
    /// next block boundary.
    pub fn write(&self, id: &str, value: f32) {
        if let Some(atomic) = self.lookup_param(id) {
            atomic.store(value, PARAM_ORDERING);
        }
    }

    /// Read a parameter value (called from audio thread — RT-safe).
    ///
    /// Returns `None` if the parameter ID is unknown. Uses
    /// `Ordering::Relaxed` — single atomic load, no allocation.
    pub fn read(&self, id: &str) -> Option<f32> {
        self.lookup_param(id)
            .map(|atomic| atomic.load(PARAM_ORDERING))
    }

    /// Copy all parameters into `output` in stable generation order.
    ///
    /// Returns the number of copied values (`min(output.len(), parameter_count())`).
    ///
    /// This is real-time safe and allocation-free, suitable for audio callback use.
    pub fn copy_all_to(&self, output: &mut [f32]) -> usize {
        let count = output.len().min(self.ordered_params.len());
        for (idx, atomic) in self.ordered_params.iter().take(count).enumerate() {
            output[idx] = atomic.load(PARAM_ORDERING);
        }
        count
    }

    fn lookup_param(&self, id: &str) -> Option<&Arc<AtomicF32>> {
        self.params.get(id)
    }
}

// Compile-time assertion: AtomicParameterBridge is Send + Sync.
// The HashMap is immutable after construction, and all values are
// accessed through atomic operations. Arc<AtomicF32> is Send + Sync,
// so Rust auto-derives these traits correctly.
const _: () = {
    fn _assert_send_sync<T: Send + Sync>() {}
    fn _check() {
        _assert_send_sync::<AtomicParameterBridge>();
    }
};

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

    fn test_params() -> Vec<ParameterInfo> {
        vec![
            ParameterInfo {
                id: "gain".to_string(),
                name: "Gain".to_string(),
                param_type: ParameterType::Float,
                value: 0.5,
                default: 0.5,
                min: 0.0,
                max: 1.0,
                unit: Some("dB".to_string()),
                group: Some("Input".to_string()),
                variants: None,
            },
            ParameterInfo {
                id: "mix".to_string(),
                name: "Mix".to_string(),
                param_type: ParameterType::Float,
                value: 1.0,
                default: 1.0,
                min: 0.0,
                max: 1.0,
                unit: Some("%".to_string()),
                group: None,
                variants: None,
            },
        ]
    }

    #[test]
    fn test_default_values() {
        let bridge = AtomicParameterBridge::new(&test_params());

        let gain = bridge.read("gain").expect("gain should exist");
        assert!(
            (gain - 0.5).abs() < f32::EPSILON,
            "gain default should be 0.5"
        );

        let mix = bridge.read("mix").expect("mix should exist");
        assert!(
            (mix - 1.0).abs() < f32::EPSILON,
            "mix default should be 1.0"
        );
    }

    #[test]
    fn test_write_and_read() {
        let bridge = AtomicParameterBridge::new(&test_params());

        bridge.write("gain", 0.75);
        let gain = bridge.read("gain").expect("gain should exist");
        assert!(
            (gain - 0.75).abs() < f32::EPSILON,
            "gain should be updated to 0.75"
        );
    }

    #[test]
    fn test_read_unknown_param() {
        let bridge = AtomicParameterBridge::new(&test_params());
        assert!(
            bridge.read("nonexistent").is_none(),
            "unknown param should return None"
        );
    }

    #[test]
    fn test_write_unknown_param_is_noop() {
        let bridge = AtomicParameterBridge::new(&test_params());
        // Should not panic
        bridge.write("nonexistent", 0.5);
    }

    #[test]
    fn test_concurrent_write_read() {
        use std::sync::Arc;
        use std::thread;

        let bridge = Arc::new(AtomicParameterBridge::new(&test_params()));

        let writer = {
            let bridge = Arc::clone(&bridge);
            thread::spawn(move || {
                for i in 0..1000 {
                    bridge.write("gain", i as f32 / 1000.0);
                }
            })
        };

        let reader = {
            let bridge = Arc::clone(&bridge);
            thread::spawn(move || {
                for _ in 0..1000 {
                    let val = bridge.read("gain");
                    assert!(val.is_some(), "gain should always be readable");
                    let v = val.unwrap();
                    assert!(
                        (0.0..=1.0).contains(&v) || v == 0.5,
                        "value should be in range"
                    );
                }
            })
        };

        writer.join().expect("writer thread should not panic");
        reader.join().expect("reader thread should not panic");
    }

    #[test]
    fn test_copy_all_to_preserves_parameter_order() {
        let bridge = AtomicParameterBridge::new(&test_params());
        bridge.write("gain", 0.75);
        bridge.write("mix", 0.25);

        let mut values = [0.0_f32; 2];
        let copied = bridge.copy_all_to(&mut values);

        assert_eq!(copied, 2);
        assert!((values[0] - 0.75).abs() < f32::EPSILON);
        assert!((values[1] - 0.25).abs() < f32::EPSILON);
    }

    #[test]
    fn test_parameter_count_matches_metadata_len() {
        let params = test_params();
        let bridge = AtomicParameterBridge::new(&params);
        assert_eq!(bridge.parameter_count(), params.len());
    }
}