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.2.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.

PicoList: Extreme Scale Performance

PicoList is a dynamic, chunked collection designed to handle massive datasets (GBs) without the performance degradation of large reallocations.

Analysis: PicoList matches Vec in memory efficiency while providing near-native access speeds at massive scales.

Note: Choosing N >= 64KB ensures peak hardware synergy and memory stability.

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;

// Option A: Static capacity (via const generics)
let mut ring = PicoRing::<u8, 4096>::new().unwrap();

// Option B: Dynamic capacity
let mut ring = PicoRing::<u8>::with_capacity(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;

// Static version
let mut queue = PicoQueue::<u32, 1024>::new_static().unwrap();

// Dynamic version
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();

4. Dynamic Chunked List (PicoList)

Optimized for massive datasets, avoids large reallocations.

use picoring::PicoList;

// 1MB chunks (131072 * 8 bytes for u64)
let mut list = PicoList::<u64, 131072>::new();

list.push(100);
list.extend_from_slice(&[200, 300, 400]);

assert_eq!(*list.get(0).unwrap(), 100);

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