pub struct RingBuffer<T> {
    buffer: Vec<T>,
    capacity: usize,
}

impl<T> RingBuffer<T> {
    pub fn get(&self, index: usize) -> &T {
        &self.buffer[index % self.capacity]  // Problem #1: Modulo is slow
    }

    pub fn get_mut(&mut self, index: usize) -> &mut T {  // Problem #2: Requires &mut self
        &mut self.buffer[index % self.capacity]
    }
}

let index = sequence % capacity;  // Division instruction: 35-90 cycles

let index = sequence & (capacity - 1);  // Bitwise AND: 1 cycle

pub fn get_mut(&mut self, index: usize) -> &mut T {
    // Requires &mut self - can't have multiple readers while writing!
}

use std::cell::UnsafeCell;

pub struct RingBuffer<T> {
    buffer: Box<[UnsafeCell<T>]>,  // Interior mutability
}

impl<T> RingBuffer<T> {
    pub fn get_mut(&self, index: usize) -> &mut T {
        // SAFETY: Caller ensures exclusive access via sequencer
        unsafe { &mut *self.buffer[index].get() }
    }
}

use std::mem::MaybeUninit;
use std::sync::atomic::{AtomicUsize, Ordering};

pub struct RingBuffer<T> {
    buffer: Box<[UnsafeCell<MaybeUninit<T>>]>,
    initialized: AtomicUsize,  // Track how many slots are initialized
}

use std::cell::UnsafeCell;
use std::mem::MaybeUninit;
use std::sync::atomic::{AtomicUsize, Ordering};

/// Pre-allocated, power-of-2, cache-aligned ring buffer
///
/// Uses cache-line padding on BOTH sides to prevent false sharing:
/// - `align(64)` ensures struct starts at cache-line boundary (64 bytes)
/// - Left padding protects actual fields from previous fields in parent struct
/// - Right padding protects actual fields from next fields in parent struct
///
/// Memory layout (192 bytes = 3 cache lines):
/// - Left padding: 64 bytes
/// - Actual fields: 32 bytes (buffer:16 + index_mask:8 + initialized:8)
/// - Right padding: 64 bytes
/// - Alignment tail padding: 32 bytes (compiler pads 160→192 for align(64))
///
/// When embedded as a field in another struct, the compiler may insert up to
/// 56 bytes of alignment padding *before* this struct to satisfy align(64).
/// This is NOT part of the struct's own size (std::mem::size_of = 192).
///
/// This guarantees complete cache-line isolation regardless of allocation location.
#[repr(C, align(64))]  // Guarantee cache-line alignment
pub struct RingBuffer<T> {
    /// Left padding (prevents false sharing with previous fields)
    _padding_left: [u8; 64],

    /// Buffer storage with interior mutability
    buffer: Box<[UnsafeCell<MaybeUninit<T>>]>,

    /// Fast indexing mask (capacity - 1)
    index_mask: usize,

    /// Number of initialized slots (for panic-safe drop).
    /// AtomicUsize is idiomatic for fields in a Sync type, though only
    /// &mut access is needed (construction and Drop both have exclusive access).
    initialized: AtomicUsize,

    /// Right padding (prevents false sharing with next fields)
    _padding_right: [u8; 64],
}

impl<T> RingBuffer<T> {
    /// Create a new ring buffer with pre-allocated events
    ///
    /// # Panics
    /// - If `size` is not a power of 2
    /// - If `factory()` panics during initialization (safe - only drops initialized slots)
    pub fn new<F>(size: usize, factory: F) -> Self
    where
        F: Fn() -> T,
        T: Send,
    {
        assert!(size > 0, "Size must be greater than 0");
        assert!(size.is_power_of_two(), "Size must be power of 2");

        // Pre-allocate buffer with uninitialized memory
        let mut buffer = Vec::with_capacity(size);

        // Initialize each slot
        // If factory() panics, buffer.len() will reflect how many were initialized
        for _ in 0..size {
            buffer.push(UnsafeCell::new(MaybeUninit::new(factory())));
        }

        // Defense-in-depth: track initialized count for Drop.
        // In the current implementation, if factory() panics above, the Vec
        // drops its already-pushed elements and we never reach Self { .. }.
        // But this field protects against future refactoring (e.g., switching
        // to raw allocation) where Drop could run on a partially-initialized
        // buffer.
        let initialized = buffer.len();

        Self {
            _padding_left: [0; 64],
            buffer: buffer.into_boxed_slice(),
            index_mask: size - 1,
            initialized: AtomicUsize::new(initialized),
            _padding_right: [0; 64],
        }
    }

    /// Get immutable reference to event at sequence.
    ///
    /// # Caller Contract (enforced by sequencer, not by this method)
    ///
    /// This method is safe to call **only** through the sequencer API, which
    /// enforces all of the following at the system level:
    /// 1. Sequence has been published (via sequencer)
    /// 2. Sequence hasn't wrapped around (buffer_size ahead of slowest consumer)
    /// 3. No concurrent mutable access to this slot
    ///
    /// Calling this method directly with an invalid sequence is **undefined
    /// behavior** — even though the method signature is not `unsafe`. We keep
    /// these methods safe for ergonomic use within the sequencer; the ring
    /// buffer is not intended to be used standalone.
    #[inline]
    pub fn get(&self, sequence: i64) -> &T {
        let index = (sequence as usize) & self.index_mask;

        // SAFETY:
        // 1. Index is masked to buffer size (can't overflow)
        // 2. Sequence barrier prevents wrap-around (covered in Post 5)
        // 3. Only one writer per slot (enforced by sequencer in Post 3)
        // 4. Slot is initialized (guaranteed by constructor)
        unsafe {
            (*self.buffer[index].get()).assume_init_ref()
        }
    }

    /// Get mutable reference to event at sequence.
    ///
    /// # Caller Contract (enforced by sequencer, not by this method)
    ///
    /// Same contract as [`get`], plus:
    /// 1. Exclusive access to this sequence (via sequencer claim)
    /// 2. No concurrent readers for this slot
    /// 3. Sequence hasn't wrapped around
    ///
    /// See [`get`] for why this is not marked `unsafe`.
    #[inline]
    pub fn get_mut(&self, sequence: i64) -> &mut T {
        let index = (sequence as usize) & self.index_mask;

        // SAFETY: Same as get(), plus:
        // 5. Caller has exclusive claim (via SequenceClaim in Post 3)
        unsafe {
            (*self.buffer[index].get()).assume_init_mut()
        }
    }

    /// Get buffer size
    #[inline]
    pub fn size(&self) -> usize {
        self.buffer.len()
    }
}

// Panic-safe drop: Only drop initialized slots
impl<T> Drop for RingBuffer<T> {
    fn drop(&mut self) {
        // SAFETY: Only drop slots that were successfully initialized
        // If factory() panicked during construction, we only drop completed slots
        let initialized = *self.initialized.get_mut();

        for i in 0..initialized {
            unsafe {
                (*self.buffer[i].get()).assume_init_drop();
            }
        }
    }
}

// RingBuffer can be sent across threads if T can
unsafe impl<T: Send> Send for RingBuffer<T> {}

// RingBuffer can be shared across threads if T: Send + Sync
// SAFETY:
// - T: Send - Required because:
//   1. RingBuffer<T> can be sent to another thread
//   2. get_mut() returns &mut T, which gives mutable access to T
//   3. If T is not Send, moving RingBuffer across threads would violate Send safety
// - T: Sync - Required because:
//   1. Multiple threads can hold &RingBuffer simultaneously
//   2. get() returns &T, which can be shared across threads
//   3. If T is not Sync, sharing &T across threads would violate Sync safety
// - The sequencer (Post 3) ensures exclusive access to slots via SequenceClaim
// - Multiple threads can safely call get() on different sequences simultaneously
// - Only one thread can call get_mut() on a given sequence (enforced by sequencer)
unsafe impl<T: Send + Sync> Sync for RingBuffer<T> {}

let index = (sequence as usize) & self.index_mask;

size = 1024, mask = 1023
sequence = 0    → index = 0
sequence = 1023 → index = 1023
sequence = 1024 → index = 0    (wraps around)
sequence = 2047 → index = 1023

(*self.buffer[index].get()).assume_init_ref()

pub fn get_mut(&self, sequence: i64) -> &mut T

// WRONG: Two mutable references to the same slot!
let event1 = rb.get_mut(seq);
let event2 = rb.get_mut(seq + buffer_size);  // Aliases event1!
event1.value = 42;  // Undefined behavior!

// RIGHT: Drop references before accessing the same slot again
{
    let event = rb.get_mut(seq);
    event.value = 42;
}  // Reference dropped
let event = rb.get_mut(seq + buffer_size);  // Now safe

// Modulo (non-power-of-2)
fn index_modulo(sequence: i64, capacity: usize) -> usize {
    (sequence as usize) % capacity  // Division instruction
}

// Bitwise AND (power-of-2)
fn index_mask(sequence: i64, mask: usize) -> usize {
    (sequence as usize) & mask  // Bitwise AND
}

; Modulo version (capacity = 1000)
mov rax, rdi          ; sequence
xor edx, edx          ; clear upper bits
mov ecx, 1000
div rcx               ; rdx = rax % rcx (35-90 cycles, low throughput)
mov rax, rdx
; Note: compilers optimize constant divisors via multiply-by-reciprocal,
; but runtime-variable capacity (our case) emits actual DIV.

; Bitwise AND version (capacity = 1024, mask = 1023)
mov rax, rdi          ; sequence
and rax, 1023         ; rax &= mask (1 cycle, high throughput)