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.

Installation

Add PicoRing to your project using cargo:

cargo add picoring

Or add it manually to your Cargo.toml:

[dependencies]

picoring = "0.1.0"

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.

Simple Benchmarks

Quick smoke tests for immediate feedback:

# Core hardware mirroring tests
cargo test --test benchmarks --release -- --nocapture

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

Professional Benchmarks (Criterion)

For statistically significant measurements and HTML reports:

cargo bench --bench ring_bench

Reports will be generated at target/criterion/report/index.html.

Performance Analysis (O-Notation)

Standard ring buffers suffer from Linear Time O(N) overhead for reads when data wraps, because they require reassembling parts into a temporary buffer.

PicoRing achieves Constant Time O(1) for all read operations. Because of hardware mirroring, the data is already linear in virtual memory. As shown in Criterion results:

• Classic Read (1MB): ~26.7 µs (microsecond) (Linear increase with size)
• PicoRing Read (1MB): ~671 ps (picosecond) (Remains constant regardless of size)

This makes PicoRing the ideal choice for high-frequency trading, real-time audio, and high-throughput network processing.

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