mkaudiolibrary 1.3.0

//! Thread-safe audio buffers for real-time concurrent processing.
//!
//! This module provides three buffer types designed for multi-threaded audio applications:
//!
//! - [`Buffer`] - General-purpose buffer with read/write locking
//! - [`PushBuffer`] - FIFO buffer for convolution and filtering operations
//! - [`CircularBuffer`] - Ring buffer with power-of-2 sizing for delay lines
//!
//! ## Thread Safety Model
//!
//! All buffers use `Arc<RwLock<...>>` internally, providing:
//! - **Multiple concurrent readers** - Any number of threads can read simultaneously
//! - **Exclusive writer access** - Writers block all other access
//! - **Clone shares data** - Cloning creates a new handle to the same underlying data
//!
//! ## RAII Guards
//!
//! Access to buffer data is controlled through guard types that implement `Deref`/`DerefMut`:
//! - `BufferReadGuard` / `BufferWriteGuard`
//! - `PushBufferReadGuard` / `PushBufferWriteGuard`
//! - `CircularBufferReadGuard` / `CircularBufferWriteGuard`
//!
//! Guards automatically release locks when dropped.
//!
//! ## Example: Shared Buffer Between Threads
//!
//! ```ignore
//! use mkaudiolibrary::buffer::Buffer;
//! use std::thread;
//!
//! let buffer = Buffer::<f64>::new(1024);
//! let buffer_clone = buffer.clone();  // Shares underlying data
//!
//! // Writer thread
//! let writer = thread::spawn(move || {
//!     let mut guard = buffer_clone.write();
//!     guard[0] = 1.0;
//! });
//!
//! // Reader thread (after writer completes)
//! writer.join().unwrap();
//! let guard = buffer.read();
//! assert_eq!(guard[0], 1.0);
//! ```
//!
//! ## Example: Delay Line with CircularBuffer
//!
//! ```ignore
//! use mkaudiolibrary::buffer::CircularBuffer;
//!
//! let delay = CircularBuffer::<f64>::new(1024).unwrap();
//! let mut guard = delay.write();
//!
//! // Write samples
//! for i in 0..100 {
//!     guard.push(i as f64);
//! }
//!
//! // Read delayed samples
//! for _ in 0..100 {
//!     let sample = guard.next();
//! }
//! ```

use std::alloc::LayoutError;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, RwLock, RwLockReadGuard, RwLockWriteGuard};

// ==========================================
// Buffer - General Purpose
// ==========================================

/// Thread-safe general-purpose audio buffer with read-write locking.
///
/// Provides concurrent access to a contiguous block of samples. Multiple readers
/// can access the buffer simultaneously, while writers get exclusive access.
///
/// # Memory Layout
/// Uses `Box<[T]>` internally for cache-friendly contiguous storage with
/// minimal allocation overhead.
///
/// # Cloning
/// Cloning a `Buffer` creates a new handle to the **same** underlying data
/// (similar to `Arc`). The reference count is tracked internally.
///
/// # Thread Safety
/// Implements `Send + Sync` for use across thread boundaries.
pub struct Buffer<T : Clone + Default + Send + Sync>
{
    inner : Arc<BufferInner<T>>
}

struct BufferInner<T : Clone + Default + Send + Sync>
{
    data : RwLock<Box<[T]>>,
    reference : AtomicUsize
}

impl<T : Clone + Default + Send + Sync> Buffer<T>
{
    /// Create a new buffer with the given length, initialized to default values.
    pub fn new(len : usize) -> Self
    {
        Self
        {
            inner : Arc::new(BufferInner
            {
                data : RwLock::new(vec![T::default(); len].into_boxed_slice()),
                reference : AtomicUsize::new(1)
            })
        }
    }

    /// Create a buffer from an existing slice (copies data).
    pub fn from_slice(slice : &[T]) -> Self
    {
        Self
        {
            inner : Arc::new(BufferInner
            {
                data : RwLock::new(slice.to_vec().into_boxed_slice()),
                reference : AtomicUsize::new(1)
            })
        }
    }

    /// Acquire a read lock for shared access.
    pub fn read(&self) -> BufferReadGuard<'_, T>
    {
        BufferReadGuard { guard : self.inner.data.read().unwrap() }
    }

    /// Try to acquire a read lock without blocking.
    pub fn try_read(&self) -> Option<BufferReadGuard<'_, T>>
    {
        self.inner.data.try_read().ok().map(|guard| BufferReadGuard { guard })
    }

    /// Acquire a write lock for exclusive access.
    pub fn write(&self) -> BufferWriteGuard<'_, T>
    {
        BufferWriteGuard { guard : self.inner.data.write().unwrap() }
    }

    /// Try to acquire a write lock without blocking.
    pub fn try_write(&self) -> Option<BufferWriteGuard<'_, T>>
    {
        self.inner.data.try_write().ok().map(|guard| BufferWriteGuard { guard })
    }

    /// Resize the buffer (acquires write lock internally).
    pub fn resize(&self, len : usize)
    {
        let mut guard = self.inner.data.write().unwrap();
        *guard = vec![T::default(); len].into_boxed_slice();
    }

    /// Get the length of the buffer.
    pub fn len(&self) -> usize
    {
        self.inner.data.read().unwrap().len()
    }

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

    /// Get the current reference count.
    pub fn ref_count(&self) -> usize { self.inner.reference.load(Ordering::Acquire) }
}

/// RAII read guard for [`Buffer`].
///
/// Provides immutable access to buffer contents. Multiple read guards can
/// exist simultaneously. Implements `Deref<Target = [T]>` for slice access.
///
/// The lock is released when this guard is dropped.
pub struct BufferReadGuard<'a, T : Clone + Default + Send + Sync>
{
    guard : RwLockReadGuard<'a, Box<[T]>>
}

impl<'a, T : Clone + Default + Send + Sync> std::ops::Deref for BufferReadGuard<'a, T>
{
    type Target = [T];
    fn deref(&self) -> &Self::Target { &self.guard }
}

impl<'a, T : Clone + Default + Send + Sync> BufferReadGuard<'a, T>
{
    /// Get the number of elements in the buffer.
    pub fn len(&self) -> usize { self.guard.len() }
    /// Check if the buffer is empty.
    pub fn is_empty(&self) -> bool { self.guard.is_empty() }
}

/// RAII write guard for [`Buffer`].
///
/// Provides exclusive mutable access to buffer contents. Only one write guard
/// can exist at a time. Implements `DerefMut<Target = [T]>` for slice access.
///
/// The lock is released when this guard is dropped.
pub struct BufferWriteGuard<'a, T : Clone + Default + Send + Sync>
{
    guard : RwLockWriteGuard<'a, Box<[T]>>
}

impl<'a, T : Clone + Default + Send + Sync> std::ops::Deref for BufferWriteGuard<'a, T>
{
    type Target = [T];
    fn deref(&self) -> &Self::Target { &self.guard }
}

impl<'a, T : Clone + Default + Send + Sync> std::ops::DerefMut for BufferWriteGuard<'a, T>
{
    fn deref_mut(&mut self) -> &mut Self::Target { &mut self.guard }
}

impl<'a, T : Clone + Default + Send + Sync> BufferWriteGuard<'a, T>
{
    /// Get the number of elements in the buffer.
    pub fn len(&self) -> usize { self.guard.len() }
    /// Check if the buffer is empty.
    pub fn is_empty(&self) -> bool { self.guard.is_empty() }
}

impl<T : Clone + Default + Send + Sync> Clone for Buffer<T>
{
    fn clone(&self) -> Self
    {
        self.inner.reference.fetch_add(1, Ordering::AcqRel);
        Self { inner : Arc::clone(&self.inner) }
    }
}

impl<T : Clone + Default + Send + Sync> Drop for Buffer<T>
{
    fn drop(&mut self)
    {
        self.inner.reference.fetch_sub(1, Ordering::AcqRel);
    }
}

unsafe impl<T : Clone + Default + Send + Sync> Send for Buffer<T> {}
unsafe impl<T : Clone + Default + Send + Sync> Sync for Buffer<T> {}

impl<T : Clone + Default + Send + Sync> Default for Buffer<T>
{
    fn default() -> Self { Self::new(0) }
}

// ==========================================
// PushBuffer - FIFO for Convolution
// ==========================================

/// Thread-safe FIFO buffer for convolution and FIR filtering.
///
/// Maintains a sliding window of samples, automatically shifting old samples
/// out as new ones are pushed. Ideal for real-time FIR filter implementations
/// where you need access to the last N samples.
///
/// # Push Behavior
/// - Until the buffer is full: samples are appended at the current index
/// - When full: samples shift left, newest sample goes at the end (FIFO)
///
/// # Use Cases
/// - FIR filter implementations
/// - Convolution with impulse responses
/// - Any DSP requiring a sliding window of samples
///
/// # Thread Safety
/// Uses `RwLock` for concurrent access. Multiple readers can access
/// simultaneously; writers get exclusive access.
pub struct PushBuffer<T : Copy + Default + Send + Sync>
{
    inner : Arc<PushBufferInner<T>>
}

struct PushBufferInner<T : Copy + Default + Send + Sync>
{
    data : RwLock<PushBufferData<T>>
}

struct PushBufferData<T : Copy + Default>
{
    buffer : Box<[T]>,
    index : usize
}

impl<T : Copy + Default + Send + Sync> PushBuffer<T>
{
    /// Create a new push buffer with the given length.
    ///
    /// Buffer is initialized with default values and the write index at 0.
    pub fn new(len : usize) -> Result<Self, LayoutError>
    {
        Ok(Self
        {
            inner : Arc::new(PushBufferInner
            {
                data : RwLock::new(PushBufferData
                {
                    buffer : vec![T::default(); len].into_boxed_slice(),
                    index : 0
                })
            })
        })
    }

    /// Create a push buffer from an existing slice.
    pub fn from_slice(slice : &[T]) -> Self
    {
        Self
        {
            inner : Arc::new(PushBufferInner
            {
                data : RwLock::new(PushBufferData
                {
                    buffer : slice.to_vec().into_boxed_slice(),
                    index : 0
                })
            })
        }
    }

    /// Acquire a read lock.
    pub fn read(&self) -> PushBufferReadGuard<'_, T>
    {
        PushBufferReadGuard { guard : self.inner.data.read().unwrap() }
    }

    /// Try to acquire a read lock without blocking.
    pub fn try_read(&self) -> Option<PushBufferReadGuard<'_, T>>
    {
        self.inner.data.try_read().ok().map(|guard| PushBufferReadGuard { guard })
    }

    /// Acquire a write lock.
    pub fn write(&self) -> PushBufferWriteGuard<'_, T>
    {
        PushBufferWriteGuard { guard : self.inner.data.write().unwrap() }
    }

    /// Try to acquire a write lock without blocking.
    pub fn try_write(&self) -> Option<PushBufferWriteGuard<'_, T>>
    {
        self.inner.data.try_write().ok().map(|guard| PushBufferWriteGuard { guard })
    }

    /// Resize the buffer, clearing all data.
    pub fn resize(&self, len : usize) -> Result<(), LayoutError>
    {
        let mut guard = self.inner.data.write().unwrap();
        guard.buffer = vec![T::default(); len].into_boxed_slice();
        guard.index = 0;
        Ok(())
    }

    /// Push a new value (acquires write lock internally).
    pub fn push(&self, value : T)
    {
        let mut guard = self.inner.data.write().unwrap();
        let len = guard.buffer.len();
        if len == 0 { return; }

        if guard.index < len
        {
            let idx = guard.index;
            guard.buffer[idx] = value;
            guard.index += 1;
        }
        else
        {
            guard.buffer.copy_within(1..len, 0);
            guard.buffer[len - 1] = value;
        }
    }

    /// Get the current write index.
    pub fn get_index(&self) -> usize { self.inner.data.read().unwrap().index }

    /// Set the write index.
    pub fn set_index(&self, index : usize)
    {
        let mut guard = self.inner.data.write().unwrap();
        guard.index = index.min(guard.buffer.len());
    }

    /// Get the length of the buffer.
    pub fn len(&self) -> usize { self.inner.data.read().unwrap().buffer.len() }

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

/// RAII read guard for [`PushBuffer`].
///
/// Provides immutable access to buffer contents and index state.
/// Implements `Deref<Target = [T]>` and `Index<usize>` for element access.
pub struct PushBufferReadGuard<'a, T : Copy + Default + Send + Sync>
{
    guard : RwLockReadGuard<'a, PushBufferData<T>>
}

impl<'a, T : Copy + Default + Send + Sync> PushBufferReadGuard<'a, T>
{
    /// Get the buffer length.
    pub fn len(&self) -> usize { self.guard.buffer.len() }
    /// Check if the buffer is empty.
    pub fn is_empty(&self) -> bool { self.guard.buffer.is_empty() }
    /// Get the current write index.
    pub fn get_index(&self) -> usize { self.guard.index }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::Deref for PushBufferReadGuard<'a, T>
{
    type Target = [T];
    fn deref(&self) -> &Self::Target { &self.guard.buffer }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::Index<usize> for PushBufferReadGuard<'a, T>
{
    type Output = T;
    fn index(&self, index : usize) -> &Self::Output { &self.guard.buffer[index] }
}

/// RAII write guard for [`PushBuffer`].
///
/// Provides exclusive mutable access to buffer contents. Supports the `push()`
/// operation for adding new samples. Implements `DerefMut<Target = [T]>` and
/// `IndexMut<usize>` for element access.
pub struct PushBufferWriteGuard<'a, T : Copy + Default + Send + Sync>
{
    guard : RwLockWriteGuard<'a, PushBufferData<T>>
}

impl<'a, T : Copy + Default + Send + Sync> PushBufferWriteGuard<'a, T>
{
    /// Get the buffer length.
    pub fn len(&self) -> usize { self.guard.buffer.len() }
    /// Check if the buffer is empty.
    pub fn is_empty(&self) -> bool { self.guard.buffer.is_empty() }
    /// Get the current write index.
    pub fn get_index(&self) -> usize { self.guard.index }

    /// Push a new sample into the buffer.
    ///
    /// If the buffer is not yet full, appends at the current index.
    /// If the buffer is full, shifts all samples left and places the new
    /// sample at the end (FIFO behavior).
    pub fn push(&mut self, value : T)
    {
        let len = self.guard.buffer.len();
        if len == 0 { return; }

        if self.guard.index < len
        {
            let idx = self.guard.index;
            self.guard.buffer[idx] = value;
            self.guard.index += 1;
        }
        else
        {
            self.guard.buffer.copy_within(1..len, 0);
            self.guard.buffer[len - 1] = value;
        }
    }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::Deref for PushBufferWriteGuard<'a, T>
{
    type Target = [T];
    fn deref(&self) -> &Self::Target { &self.guard.buffer }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::DerefMut for PushBufferWriteGuard<'a, T>
{
    fn deref_mut(&mut self) -> &mut Self::Target { &mut self.guard.buffer }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::Index<usize> for PushBufferWriteGuard<'a, T>
{
    type Output = T;
    fn index(&self, index : usize) -> &Self::Output { &self.guard.buffer[index] }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::IndexMut<usize> for PushBufferWriteGuard<'a, T>
{
    fn index_mut(&mut self, index : usize) -> &mut Self::Output { &mut self.guard.buffer[index] }
}

impl<T : Copy + Default + Send + Sync> Clone for PushBuffer<T>
{
    fn clone(&self) -> Self { Self { inner : Arc::clone(&self.inner) } }
}

unsafe impl<T : Copy + Default + Send + Sync> Send for PushBuffer<T> {}
unsafe impl<T : Copy + Default + Send + Sync> Sync for PushBuffer<T> {}

// ==========================================
// CircularBuffer - Ring Buffer for Delay Lines
// ==========================================

/// Thread-safe circular buffer (ring buffer) for delay lines.
///
/// A fixed-size buffer where the read and write positions wrap around,
/// creating an infinite stream effect. Ideal for delay effects, lookahead
/// buffers, and any application requiring a fixed-length sample history.
///
/// # Power-of-2 Sizing
/// The buffer length is automatically rounded up to the next power of 2.
/// This enables efficient index wrapping using bitwise AND instead of modulo,
/// which is significantly faster in tight audio processing loops.
///
/// # Read/Write Pointers
/// - `push()` - Write a sample at the write position and advance
/// - `next()` - Read a sample from the read position and advance
/// - `peek()` - Read without advancing
///
/// # Thread Safety
/// Uses `RwLock` for concurrent access. Multiple readers can access
/// simultaneously; writers get exclusive access.
///
/// # Example
/// ```ignore
/// let delay = CircularBuffer::<f64>::new(256).unwrap();  // Rounds to 256 (power of 2)
/// let mut guard = delay.write();
/// guard.push(1.0);  // Write sample
/// let sample = guard.next();  // Read delayed sample
/// ```
pub struct CircularBuffer<T : Copy + Default + Send + Sync>
{
    inner : Arc<CircularBufferInner<T>>
}

struct CircularBufferInner<T : Copy + Default + Send + Sync>
{
    data : RwLock<CircularBufferData<T>>
}

struct CircularBufferData<T : Copy + Default>
{
    buffer : Box<[T]>,
    read : usize,
    write : usize,
    mask : usize  // For efficient modulo: index & mask
}

impl<T : Copy + Default + Send + Sync> CircularBuffer<T>
{
    /// Create a new circular buffer with the given length.
    ///
    /// The actual length is rounded up to the next power of 2 for
    /// efficient index wrapping. For example, requesting 100 samples
    /// will allocate 128.
    pub fn new(len : usize) -> Result<Self, LayoutError>
    {
        let actual_len = len.next_power_of_two().max(1);
        Ok(Self
        {
            inner : Arc::new(CircularBufferInner
            {
                data : RwLock::new(CircularBufferData
                {
                    buffer : vec![T::default(); actual_len].into_boxed_slice(),
                    read : 0,
                    write : 0,
                    mask : actual_len - 1
                })
            })
        })
    }

    /// Create a circular buffer from an existing slice.
    pub fn from_slice(slice : &[T]) -> Self
    {
        let len = slice.len().next_power_of_two().max(1);
        let mut buffer = vec![T::default(); len];
        buffer[..slice.len()].copy_from_slice(slice);
        Self
        {
            inner : Arc::new(CircularBufferInner
            {
                data : RwLock::new(CircularBufferData
                {
                    buffer : buffer.into_boxed_slice(),
                    read : 0,
                    write : slice.len() & (len - 1),
                    mask : len - 1
                })
            })
        }
    }

    /// Acquire a read lock.
    pub fn read(&self) -> CircularBufferReadGuard<'_, T>
    {
        CircularBufferReadGuard { guard : self.inner.data.read().unwrap() }
    }

    /// Try to acquire a read lock without blocking.
    pub fn try_read(&self) -> Option<CircularBufferReadGuard<'_, T>>
    {
        self.inner.data.try_read().ok().map(|guard| CircularBufferReadGuard { guard })
    }

    /// Acquire a write lock.
    pub fn write(&self) -> CircularBufferWriteGuard<'_, T>
    {
        CircularBufferWriteGuard { guard : self.inner.data.write().unwrap() }
    }

    /// Try to acquire a write lock without blocking.
    pub fn try_write(&self) -> Option<CircularBufferWriteGuard<'_, T>>
    {
        self.inner.data.try_write().ok().map(|guard| CircularBufferWriteGuard { guard })
    }

    /// Resize the buffer, clearing all data.
    pub fn resize(&self, len : usize) -> Result<(), LayoutError>
    {
        let actual_len = len.next_power_of_two().max(1);
        let mut guard = self.inner.data.write().unwrap();
        guard.buffer = vec![T::default(); actual_len].into_boxed_slice();
        guard.read = 0;
        guard.write = 0;
        guard.mask = actual_len - 1;
        Ok(())
    }

    /// Push a value and advance write pointer (acquires write lock).
    pub fn push(&self, value : T)
    {
        let mut guard = self.inner.data.write().unwrap();
        let idx = guard.write;
        guard.buffer[idx] = value;
        guard.write = (guard.write + 1) & guard.mask;
    }

    /// Read the next value and advance read pointer (acquires write lock).
    pub fn next(&self) -> T
    {
        let mut guard = self.inner.data.write().unwrap();
        let value = guard.buffer[guard.read];
        guard.read = (guard.read + 1) & guard.mask;
        value
    }

    /// Peek at value without advancing (acquires read lock).
    pub fn peek(&self) -> T
    {
        let guard = self.inner.data.read().unwrap();
        guard.buffer[guard.read]
    }

    /// Get capacity (power of 2).
    pub fn capacity(&self) -> usize { self.inner.data.read().unwrap().buffer.len() }

    /// Get logical length.
    pub fn len(&self) -> usize { self.inner.data.read().unwrap().mask + 1 }

    /// Check if empty.
    pub fn is_empty(&self) -> bool { self.capacity() == 0 }

    /// Clear buffer to default values.
    pub fn clear(&self)
    {
        let mut guard = self.inner.data.write().unwrap();
        guard.buffer.fill(T::default());
        guard.read = 0;
        guard.write = 0;
    }
}

/// RAII read guard for [`CircularBuffer`].
///
/// Provides immutable access to buffer contents and pointer state.
/// Implements `Deref<Target = [T]>` for raw buffer access and
/// `Index<usize>` with automatic index wrapping.
pub struct CircularBufferReadGuard<'a, T : Copy + Default + Send + Sync>
{
    guard : RwLockReadGuard<'a, CircularBufferData<T>>
}

impl<'a, T : Copy + Default + Send + Sync> CircularBufferReadGuard<'a, T>
{
    /// Get the logical buffer length (power of 2).
    pub fn len(&self) -> usize { self.guard.mask + 1 }
    /// Get the actual buffer capacity.
    pub fn capacity(&self) -> usize { self.guard.buffer.len() }
    /// Get the current read pointer position.
    pub fn get_read(&self) -> usize { self.guard.read }
    /// Get the current write pointer position.
    pub fn get_write(&self) -> usize { self.guard.write }
    /// Peek at the sample at the read position without advancing.
    pub fn peek(&self) -> T { self.guard.buffer[self.guard.read] }

    /// Read a sample at an offset from the read position.
    ///
    /// Index wraps automatically using the buffer mask.
    pub fn read_offset(&self, offset : usize) -> T
    {
        self.guard.buffer[(self.guard.read + offset) & self.guard.mask]
    }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::Deref for CircularBufferReadGuard<'a, T>
{
    type Target = [T];
    fn deref(&self) -> &Self::Target { &self.guard.buffer }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::Index<usize> for CircularBufferReadGuard<'a, T>
{
    type Output = T;
    fn index(&self, index : usize) -> &Self::Output { &self.guard.buffer[index & self.guard.mask] }
}

/// RAII write guard for [`CircularBuffer`].
///
/// Provides exclusive mutable access to buffer contents. Supports ring buffer
/// operations (`push`, `next`, `peek`) and direct element access via
/// `DerefMut<Target = [T]>` and `IndexMut<usize>` with automatic wrapping.
pub struct CircularBufferWriteGuard<'a, T : Copy + Default + Send + Sync>
{
    guard : RwLockWriteGuard<'a, CircularBufferData<T>>
}

impl<'a, T : Copy + Default + Send + Sync> CircularBufferWriteGuard<'a, T>
{
    /// Get the logical buffer length (power of 2).
    pub fn len(&self) -> usize { self.guard.mask + 1 }
    /// Get the actual buffer capacity.
    pub fn capacity(&self) -> usize { self.guard.buffer.len() }
    /// Get the current read pointer position.
    pub fn get_read(&self) -> usize { self.guard.read }
    /// Get the current write pointer position.
    pub fn get_write(&self) -> usize { self.guard.write }

    /// Write a sample at the write position and advance the pointer.
    ///
    /// The pointer wraps automatically when reaching the buffer end.
    #[inline]
    pub fn push(&mut self, value : T)
    {
        let idx = self.guard.write;
        self.guard.buffer[idx] = value;
        self.guard.write = (self.guard.write + 1) & self.guard.mask;
    }

    /// Read a sample from the read position and advance the pointer.
    ///
    /// The pointer wraps automatically when reaching the buffer end.
    #[inline]
    pub fn next(&mut self) -> T
    {
        let value = self.guard.buffer[self.guard.read];
        self.guard.read = (self.guard.read + 1) & self.guard.mask;
        value
    }

    /// Peek at the sample at the read position without advancing.
    pub fn peek(&self) -> T { self.guard.buffer[self.guard.read] }

    /// Read a sample at an offset from the read position.
    ///
    /// Index wraps automatically using the buffer mask.
    pub fn read_offset(&self, offset : usize) -> T
    {
        self.guard.buffer[(self.guard.read + offset) & self.guard.mask]
    }

    /// Write a sample at an offset from the write position.
    ///
    /// Index wraps automatically using the buffer mask.
    pub fn write_offset(&mut self, offset : usize, value : T)
    {
        let idx = (self.guard.write + offset) & self.guard.mask;
        self.guard.buffer[idx] = value;
    }

    /// Set the read pointer position (masked to valid range).
    pub fn set_read(&mut self, index : usize) { self.guard.read = index & self.guard.mask; }

    /// Set the write pointer position (masked to valid range).
    pub fn set_write(&mut self, index : usize) { self.guard.write = index & self.guard.mask; }

    /// Clear the buffer to default values and reset pointers.
    pub fn clear(&mut self)
    {
        self.guard.buffer.fill(T::default());
        self.guard.read = 0;
        self.guard.write = 0;
    }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::Deref for CircularBufferWriteGuard<'a, T>
{
    type Target = [T];
    fn deref(&self) -> &Self::Target { &self.guard.buffer }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::DerefMut for CircularBufferWriteGuard<'a, T>
{
    fn deref_mut(&mut self) -> &mut Self::Target { &mut self.guard.buffer }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::Index<usize> for CircularBufferWriteGuard<'a, T>
{
    type Output = T;
    fn index(&self, index : usize) -> &Self::Output { &self.guard.buffer[index & self.guard.mask] }
}

impl<'a, T : Copy + Default + Send + Sync> std::ops::IndexMut<usize> for CircularBufferWriteGuard<'a, T>
{
    fn index_mut(&mut self, index : usize) -> &mut Self::Output
    {
        let idx = index & self.guard.mask;
        &mut self.guard.buffer[idx]
    }
}

impl<T : Copy + Default + Send + Sync> Clone for CircularBuffer<T>
{
    fn clone(&self) -> Self { Self { inner : Arc::clone(&self.inner) } }
}

unsafe impl<T : Copy + Default + Send + Sync> Send for CircularBuffer<T> {}
unsafe impl<T : Copy + Default + Send + Sync> Sync for CircularBuffer<T> {}