Module buffer 

Pinned buffer management for educational and benchmarking purposes.

⚠️ Important: PinnedBuffer is NOT for I/O Operations

This module provides PinnedBuffer<T> primarily for educational purposes and allocation benchmarking. The PinnedBuffer type is fundamentally limited by Rust’s lifetime system and cannot be used for practical I/O operations such as loops or concurrent operations.

For all I/O operations, use OwnedBuffer with the *_owned methods on Ring.

Key Features

• Memory Pinning: Guarantees stable memory addresses using Pin<Box<T>>
• Generation Tracking: Atomic counters for buffer lifecycle debugging
• NUMA Awareness: Platform-specific NUMA-aware allocation (Linux) - useful for benchmarking
• DMA Optimization: Page-aligned allocation for optimal hardware performance - useful for benchmarking
• Thread Safety: Safe sharing and transfer between threads

Valid Usage Examples

use safer_ring::buffer::PinnedBuffer;

// ✅ VALID: Allocation benchmarking
let standard_buffer = PinnedBuffer::with_capacity(4096);
let aligned_buffer = PinnedBuffer::with_capacity_aligned(4096);
let numa_buffer = PinnedBuffer::with_capacity_numa(4096, Some(0));

// ✅ VALID: Single operation, then immediate drop
let data = b"Hello, io_uring!".to_vec();
let buffer = PinnedBuffer::from_vec(data);
assert_eq!(buffer.as_slice(), b"Hello, io_uring!");

Invalid Usage (Will Not Compile)

use safer_ring::{Ring, buffer::PinnedBuffer};

let mut ring = Ring::new(32)?;
let mut buffer = PinnedBuffer::with_capacity(4096);

// ❌ BROKEN: This will not compile due to lifetime constraints
for _ in 0..2 {
    let (_, buf) = ring.read(0, buffer.as_mut_slice())?.await?;
    buffer = buf;  // Error: ring is still borrowed
}

The Technical Problem

Methods like Ring::read() return futures that hold mutable borrows of both the Ring and buffer for their entire lifetime. Rust’s borrow checker prevents subsequent operations until the borrow is released, making loops and concurrent operations impossible.

Re-exports

pub use allocation::*;

pub use generation::*;

pub use numa::*;

Modules

allocation

Memory allocation utilities for creating aligned and optimized buffers.

generation

Generation tracking utilities for buffer lifecycle management.

numa

NUMA-aware buffer allocation for multi-socket systems.

Structs

PinnedBuffer

A buffer that is pinned in memory, primarily for educational purposes.