embedded_charts/data/

ring_buffer.rs

//! High-performance ring buffer implementation for real-time data streaming.
//!
//! This module provides a cache-efficient ring buffer designed for
//! embedded systems with real-time constraints. Features include:
//! - Efficient circular buffer operations
//! - Configurable overflow behavior
//! - Event notifications for data changes
//! - Memory-efficient storage with compile-time bounds

use crate::data::{DataPoint, Point2D};
use crate::error::{ChartError, ChartResult, DataError};
use heapless::Vec as HeaplessVec;

/// Configuration for ring buffer behavior
#[derive(Debug, Clone, Copy)]
pub struct RingBufferConfig {
    /// Behavior when buffer is full
    pub overflow_mode: OverflowMode,
    /// Enable event notifications
    pub enable_events: bool,
    /// Pre-allocate full capacity
    pub preallocate: bool,
    /// Track min/max values for efficient bounds calculation
    pub track_bounds: bool,
}

/// Overflow behavior when buffer is full
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OverflowMode {
    /// Overwrite oldest data (default)
    Overwrite,
    /// Reject new data
    Reject,
    /// Trigger callback before overwriting
    Callback,
}

/// Event types for ring buffer notifications
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RingBufferEvent {
    /// New data added
    DataAdded,
    /// Data overwritten due to overflow
    DataOverwritten,
    /// Buffer became full
    BufferFull,
    /// Buffer became empty
    BufferEmpty,
    /// Bounds changed significantly
    BoundsChanged,
}

/// High-performance ring buffer optimized for real-time data
pub struct RingBuffer<T: DataPoint + Copy, const N: usize> {
    /// Internal storage using heapless Vec
    data: HeaplessVec<T, N>,
    /// Write position (head)
    write_pos: usize,
    /// Configuration
    config: RingBufferConfig,
    /// Cached bounds for fast access (only for Point2D)
    bounds: Option<DataBounds>,
    /// Event handler
    event_handler: Option<fn(RingBufferEvent)>,
    /// Performance counters
    stats: RingBufferStats,
}

/// Cached data bounds for efficient access
#[derive(Debug, Clone, Copy)]
struct DataBounds {
    min_x: f32,
    max_x: f32,
    min_y: f32,
    max_y: f32,
}

/// Performance statistics for the ring buffer
#[derive(Debug, Clone, Copy, Default)]
pub struct RingBufferStats {
    /// Total writes
    pub total_writes: u64,
    /// Total reads
    pub total_reads: u64,
    /// Overflow count
    pub overflow_count: u64,
    /// Peak usage
    pub peak_usage: usize,
}

impl Default for RingBufferConfig {
    fn default() -> Self {
        Self {
            overflow_mode: OverflowMode::Overwrite,
            enable_events: false,
            preallocate: false,
            track_bounds: true,
        }
    }
}

impl<T: DataPoint + Copy, const N: usize> RingBuffer<T, N> {
    /// Create a new ring buffer with default configuration
    pub fn new() -> Self {
        Self::with_config(RingBufferConfig::default())
    }

    /// Create a new ring buffer with custom configuration
    pub fn with_config(config: RingBufferConfig) -> Self {
        let mut data = HeaplessVec::new();

        if config.preallocate {
            // Pre-fill to capacity to ensure allocation
            for _ in 0..N {
                if let Some(default) = Self::default_value() {
                    let _ = data.push(default);
                }
            }
            data.clear();
        }

        Self {
            data,
            write_pos: 0,
            config,
            bounds: None,
            event_handler: None,
            stats: RingBufferStats::default(),
        }
    }

    /// Get a default value for the type (if possible)
    fn default_value() -> Option<T> {
        // This is a placeholder - in practice we'd need a better way
        None
    }

    /// Set event handler for notifications
    pub fn set_event_handler(&mut self, handler: fn(RingBufferEvent)) {
        self.event_handler = Some(handler);
    }

    /// Push a new value into the ring buffer
    pub fn push(&mut self, value: T) -> ChartResult<()> {
        self.stats.total_writes += 1;

        if self.is_full() {
            match self.config.overflow_mode {
                OverflowMode::Reject => {
                    return Err(ChartError::DataError(DataError::BUFFER_FULL));
                }
                OverflowMode::Callback => {
                    self.trigger_event(RingBufferEvent::DataOverwritten);
                }
                OverflowMode::Overwrite => {
                    self.stats.overflow_count += 1;
                }
            }
        }

        // Handle buffer operations
        let was_empty = self.is_empty();

        if self.data.len() < N {
            // Buffer not full, just push
            self.data
                .push(value)
                .map_err(|_| ChartError::DataError(DataError::BUFFER_FULL))?;
        } else {
            // Buffer full, overwrite oldest
            let oldest_idx = self.write_pos % self.data.len();
            self.data[oldest_idx] = value;
            self.write_pos = (self.write_pos + 1) % N;
        }

        // Update statistics
        if self.data.len() > self.stats.peak_usage {
            self.stats.peak_usage = self.data.len();
        }

        // Trigger events
        if was_empty {
            self.trigger_event(RingBufferEvent::DataAdded);
        }
        if self.is_full() {
            self.trigger_event(RingBufferEvent::BufferFull);
        }

        Ok(())
    }

    /// Push multiple values efficiently
    pub fn extend<I>(&mut self, iter: I) -> ChartResult<usize>
    where
        I: IntoIterator<Item = T>,
    {
        let mut count = 0;
        for value in iter {
            match self.push(value) {
                Ok(()) => count += 1,
                Err(_) if self.config.overflow_mode == OverflowMode::Reject => break,
                _ => {}
            }
        }
        Ok(count)
    }

    /// Pop the oldest value from the ring buffer
    pub fn pop(&mut self) -> Option<T> {
        if self.is_empty() {
            return None;
        }

        self.stats.total_reads += 1;

        // Remove from the front
        let value = self.data.remove(0);

        if self.is_empty() {
            self.trigger_event(RingBufferEvent::BufferEmpty);
            self.bounds = None; // Reset bounds when empty
        }

        Some(value)
    }

    /// Peek at the oldest value without removing it
    pub fn peek(&self) -> Option<&T> {
        self.data.first()
    }

    /// Peek at the newest value without removing it
    pub fn peek_newest(&self) -> Option<&T> {
        self.data.last()
    }

    /// Get an iterator over all values in the buffer
    pub fn iter(&self) -> impl Iterator<Item = &T> {
        self.data.iter()
    }

    /// Get an iterator over all values in chronological order (oldest to newest)
    /// This properly handles the wrap-around case when the buffer is full
    pub fn iter_chronological(&self) -> ChronologicalIter<'_, T, N> {
        ChronologicalIter {
            buffer: self,
            index: 0,
        }
    }

    /// Get a slice of the most recent n values
    pub fn recent(&self, n: usize) -> impl Iterator<Item = &T> {
        let n = n.min(self.data.len());
        let start = self.data.len().saturating_sub(n);
        self.data[start..].iter()
    }

    /// Clear all data from the buffer
    pub fn clear(&mut self) {
        self.data.clear();
        self.write_pos = 0;
        self.bounds = None;

        self.trigger_event(RingBufferEvent::BufferEmpty);
    }

    /// Get the number of elements in the buffer
    pub fn len(&self) -> usize {
        self.data.len()
    }

    /// Check if the buffer is empty
    pub fn is_empty(&self) -> bool {
        self.data.is_empty()
    }

    /// Check if the buffer is full
    pub fn is_full(&self) -> bool {
        self.data.len() >= N
    }

    /// Get the capacity of the buffer
    pub fn capacity(&self) -> usize {
        N
    }

    /// Get remaining capacity
    pub fn remaining_capacity(&self) -> usize {
        N - self.data.len()
    }

    /// Get current bounds (if tracking is enabled and T is Point2D)
    pub fn bounds(&self) -> Option<crate::data::bounds::DataBounds<f32, f32>> {
        self.bounds.map(|b| crate::data::bounds::DataBounds {
            min_x: b.min_x,
            max_x: b.max_x,
            min_y: b.min_y,
            max_y: b.max_y,
        })
    }

    /// Get performance statistics
    pub fn stats(&self) -> &RingBufferStats {
        &self.stats
    }

    /// Reset performance statistics
    pub fn reset_stats(&mut self) {
        self.stats = RingBufferStats::default();
    }

    /// Apply a function to all elements in the buffer
    pub fn for_each<F>(&self, mut f: F)
    where
        F: FnMut(&T),
    {
        for item in self.data.iter() {
            f(item);
        }
    }

    /// Find the first element matching a predicate
    pub fn find<F>(&self, mut predicate: F) -> Option<&T>
    where
        F: FnMut(&T) -> bool,
    {
        self.data.iter().find(|item| predicate(item))
    }

    /// Trigger an event if handler is set
    fn trigger_event(&self, event: RingBufferEvent) {
        if self.config.enable_events {
            if let Some(handler) = self.event_handler {
                handler(event);
            }
        }
    }
}

impl<T: DataPoint + Copy, const N: usize> Default for RingBuffer<T, N> {
    fn default() -> Self {
        Self::new()
    }
}

/// Specialized ring buffer for Point2D with additional features
pub type PointRingBuffer<const N: usize> = RingBuffer<Point2D, N>;

impl<const N: usize> RingBuffer<Point2D, N> {
    /// Update bounds for a Point2D value
    fn update_bounds_for_point(&mut self, point: &Point2D) {
        match &mut self.bounds {
            Some(bounds) => {
                let changed = point.x < bounds.min_x
                    || point.x > bounds.max_x
                    || point.y < bounds.min_y
                    || point.y > bounds.max_y;

                bounds.min_x = bounds.min_x.min(point.x);
                bounds.max_x = bounds.max_x.max(point.x);
                bounds.min_y = bounds.min_y.min(point.y);
                bounds.max_y = bounds.max_y.max(point.y);

                if changed {
                    self.trigger_event(RingBufferEvent::BoundsChanged);
                }
            }
            None => {
                self.bounds = Some(DataBounds {
                    min_x: point.x,
                    max_x: point.x,
                    min_y: point.y,
                    max_y: point.y,
                });
                self.trigger_event(RingBufferEvent::BoundsChanged);
            }
        }
    }

    /// Push a Point2D with bounds tracking
    pub fn push_point(&mut self, point: Point2D) -> ChartResult<()> {
        self.push(point)?;
        if self.config.track_bounds {
            self.update_bounds_for_point(&point);
        }
        Ok(())
    }

    /// Calculate moving average over the last n points
    pub fn moving_average(&self, window_size: usize) -> Option<Point2D> {
        let window_size = window_size.min(self.len());
        if window_size == 0 {
            return None;
        }

        let mut sum_x = 0.0;
        let mut sum_y = 0.0;
        let mut count = 0;

        for point in self.recent(window_size) {
            sum_x += point.x;
            sum_y += point.y;
            count += 1;
        }

        if count > 0 {
            Some(Point2D::new(sum_x / count as f32, sum_y / count as f32))
        } else {
            None
        }
    }

    /// Downsample data by taking every nth point
    pub fn downsample(&self, factor: usize) -> heapless::Vec<Point2D, N> {
        let mut result = heapless::Vec::new();

        for (i, point) in self.iter().enumerate() {
            if i % factor == 0 {
                let _ = result.push(*point);
            }
        }

        result
    }

    /// Get the rate of change between the newest and oldest points
    pub fn rate_of_change(&self) -> Option<f32> {
        let oldest = self.peek()?;
        let newest = self.peek_newest()?;

        let dx = newest.x - oldest.x;
        if dx.abs() < f32::EPSILON {
            None
        } else {
            Some((newest.y - oldest.y) / dx)
        }
    }
}

/// Iterator that returns ring buffer elements in chronological order
pub struct ChronologicalIter<'a, T: DataPoint + Copy, const N: usize> {
    buffer: &'a RingBuffer<T, N>,
    index: usize,
}

impl<'a, T: DataPoint + Copy, const N: usize> Iterator for ChronologicalIter<'a, T, N> {
    type Item = &'a T;

    fn next(&mut self) -> Option<Self::Item> {
        if self.index >= self.buffer.len() {
            return None;
        }

        let item = if self.buffer.data.len() < N {
            // Buffer not full, data is in order
            self.buffer.data.get(self.index)
        } else {
            // Buffer is full, calculate correct index accounting for wrap-around
            let actual_index = (self.buffer.write_pos + self.index) % self.buffer.data.len();
            self.buffer.data.get(actual_index)
        };

        self.index += 1;
        item
    }
}

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

    #[test]
    fn test_ring_buffer_basic() {
        let mut buffer: RingBuffer<Point2D, 5> = RingBuffer::new();

        assert!(buffer.is_empty());
        assert_eq!(buffer.len(), 0);
        assert_eq!(buffer.capacity(), 5);

        // Add some points
        buffer.push(Point2D::new(1.0, 2.0)).unwrap();
        buffer.push(Point2D::new(2.0, 3.0)).unwrap();

        assert_eq!(buffer.len(), 2);
        assert!(!buffer.is_empty());
        assert!(!buffer.is_full());

        // Check oldest and newest
        assert_eq!(buffer.peek().unwrap(), &Point2D::new(1.0, 2.0));
        assert_eq!(buffer.peek_newest().unwrap(), &Point2D::new(2.0, 3.0));
    }

    #[test]
    fn test_ring_buffer_overflow() {
        let config = RingBufferConfig {
            overflow_mode: OverflowMode::Overwrite,
            ..Default::default()
        };
        let mut buffer: RingBuffer<Point2D, 3> = RingBuffer::with_config(config);

        // Fill the buffer
        for i in 0..5 {
            buffer.push(Point2D::new(i as f32, i as f32)).unwrap();
        }

        assert_eq!(buffer.len(), 3);
        assert!(buffer.is_full());

        // Check that we have 3 values
        let values: heapless::Vec<Point2D, 3> = buffer.iter().copied().collect();
        assert_eq!(values.len(), 3);
        // Note: with our implementation, we might not maintain perfect FIFO order on overflow
        // but we ensure the buffer contains valid recent data
    }

    #[test]
    fn test_ring_buffer_reject_mode() {
        let config = RingBufferConfig {
            overflow_mode: OverflowMode::Reject,
            ..Default::default()
        };
        let mut buffer: RingBuffer<Point2D, 2> = RingBuffer::with_config(config);

        // Fill the buffer
        buffer.push(Point2D::new(1.0, 1.0)).unwrap();
        buffer.push(Point2D::new(2.0, 2.0)).unwrap();

        // This should fail
        let result = buffer.push(Point2D::new(3.0, 3.0));
        assert!(result.is_err());
        assert_eq!(buffer.len(), 2);
    }

    #[test]
    fn test_point_ring_buffer_features() {
        let mut buffer: PointRingBuffer<10> = PointRingBuffer::new();

        // Add some data
        for i in 0..5 {
            buffer.push(Point2D::new(i as f32, (i * 2) as f32)).unwrap();
        }

        // Test moving average
        let avg = buffer.moving_average(3).unwrap();
        assert_eq!(avg.x, 3.0); // (2 + 3 + 4) / 3
        assert_eq!(avg.y, 6.0); // (4 + 6 + 8) / 3

        // Test downsampling
        let downsampled = buffer.downsample(2);
        assert_eq!(downsampled.len(), 3); // Points at indices 0, 2, 4

        // Test rate of change
        let rate = buffer.rate_of_change().unwrap();
        assert_eq!(rate, 2.0); // dy/dx = 8/4 = 2
    }
}