PicoRing

PicoRing is a high-performance circular buffer (Ring Buffer) for Rust that uses Hardware Memory Mirroring to provide a contiguous virtual memory view of circular data.

By mapping the same physical memory to two adjacent virtual address ranges, PicoRing allows you to access any part of the circular buffer as a single, contiguous slice (&[T]), even if it wraps around the end. This eliminates the need for manual wrapping logic and extra copies.

Performance Benchmarks

Below are the complete benchmark results comparing PicoRing against a classic vector-based ring buffer implementation.

1. Read Performance (Zero-Copy vs Reassemble)

Description: Accessing a contiguous slice of data that wraps around the buffer.

2. Full Cycle Performance (Write + Read)

Description: Combined time to write a packet and read it back immediately.

3. Write Performance (Cross-Boundary Copy)

Description: Copying data into the ring buffer when it crosses the physical boundary.

Collection Performance Showdown

Comparison between high-level collections and classic manual wrap logic.

How to Run Benchmarks

You can reproduce these results on your local machine:

# Core performance tests
cargo test --test benchmarks --release -- --nocapture

# High-level collections tests
cargo test --test collections_bench --release -- --nocapture

Usage Examples

1. Basic Ring Buffer (PicoRing)

Fundamental access to the mirrored buffer.

use picoring::PicoRing;

let mut ring = PicoRing::<u8>::new(1024).unwrap();
ring.push(42);
let slice = ring.readable_slice(); // Always a contiguous slice
assert_eq!(slice[0], 42);

2. Zero-Copy Queue (PicoQueue)

Reservation-based API for maximum performance.

use picoring::PicoQueue;

let mut queue = PicoQueue::<u32>::new(1024).unwrap();

// Write directly into reserved memory
if let Some(buf) = queue.reserve(2) {
    buf[0] = 10;
    buf[1] = 20;
    queue.commit(2);
}

// Read without copying
let data = queue.peek();
queue.release(data.len());

3. Byte Stream (PicoByteStream)

Implementation of standard Read and Write traits.

use picoring::PicoByteStream;
use std::io::{Read, Write};

let mut stream = PicoByteStream::new(4096).unwrap();
stream.write_all(b"Hello Pico").unwrap();

Real-World Scenarios

Architecture examples in the scenarios/ directory:

• Audio Processing: High-speed, contiguous DSP processing.
• Network Stream: Efficient stream reassembly without copies.
• Log Analysis: Fast moving window algorithms.
• Message Passing: Inter-thread zero-copy communication.

License

MIT / Apache-2.0