Bounded Ring Buffer

A zero-dependency, fixed-capacity ring buffer designed for high-performance networking workloads with predictable memory behavior and an ergonomic byte-oriented API.

Why This Exists

This crate was created while building networking transport code and a Redis-like data flow layer. The goal was a simple, fast, dependency-free structure that is tuned for network transmission and buffered data handling. Existing crates did not give enough control over how data flows through the buffer, so this crate was split out to reuse across future projects and to become more generally useful over time.

Features

Zero dependencies: No external crates required.
Predictable memory: Fixed capacity, no dynamic allocations during operation.
Overwrite-on-full semantics: Automatically drops oldest data when buffer is full.
Byte-oriented API: Specialized methods for numeric types (u8–u128, i8–i128, f32, f64, usize, isize) with big-endian encoding.
Flexible operations: Slice-based enqueue/dequeue for batch operations.
Comprehensive tests: 60+ test cases covering wrap-around, overwrite, and edge cases.

Quick Start

use refraction_types::BoundedRingBuffer;

fn main() {
    let mut buffer = BoundedRingBuffer::<u8>::with_capacity(10);
    
    // Enqueue some data
    buffer.enqueue(42);
    buffer.enqueue(100);
    
    // Peek without consuming
    assert_eq!(buffer.peek_u16(), Some(42 * 256 + 100));
    
    // Or dequeue to consume
    let value = buffer.dequeue();
    assert_eq!(value, Some(42));
}

Semantics

front(): Returns reference to the oldest (next to be dequeued) element.
back(): Returns reference to the newest (most recently enqueued) element.
peek_*(): Non-consuming read of a typed value from the front.
dequeue_*(): Consuming read; advances the read pointer.
enqueue(): Adds a single element; overwrites oldest if full.
advance(size): Simulates writing size bytes as if they were enqueued.

Byte-Oriented Specializations

The buffer provides typed methods for common network data types, all using big-endian encoding:

let mut buf = BoundedRingBuffer::<u8>::with_capacity(100);

buf.enqueue_u16(0xCAFE);
buf.enqueue_i32(-12345);
buf.enqueue_f64(3.14);

assert_eq!(buf.peek_u16(), Some(0xCAFE));
assert_eq!(buf.dequeue_i32(), Some(-12345));

Current Limitations & Roadmap

Thread-safe variants (SPSC, MPSC)
Custom allocators
No-std support
Zero-copy slice views
Benchmarks vs. std collections

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

refraction-types 0.1.0