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.
Primary batch API: enqueue_slice/dequeue_slice for transport-friendly chunked I/O.
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.

Examples

enqueue/dequeue

use refraction_types::ring_buffer::BoundedRingBuffer;

fn main() {
    let mut buffer = BoundedRingBuffer::<u8>::with_capacity(8);

    buffer.enqueue(10);
    buffer.enqueue(20);

    assert_eq!(buffer.dequeue(), Some(10));
    assert_eq!(buffer.dequeue(), Some(20));
    assert_eq!(buffer.dequeue(), None);
}

enqueue_slice/dequeue_slice

use refraction_types::ring_buffer::BoundedRingBuffer;

fn main() {
    let mut buffer = BoundedRingBuffer::<u8>::with_capacity(8);

    // Main data path: batch enqueue/dequeue.
    buffer.enqueue_slice(&[1, 2, 3, 4]);

    let mut out = [0_u8; 4];
    let read = buffer.dequeue_slice(&mut out, 4);
    assert_eq!(read, 4);
    assert_eq!(out, [1, 2, 3, 4]);
}

Main Data Path: enqueue_slice/dequeue_slice

For transport/protocol workloads, treat enqueue_slice and dequeue_slice as the primary API:

enqueue_slice(&[T]) appends a chunk while preserving order.
dequeue_slice(&mut [T], n) drains up to n elements into a caller-provided buffer.
If input chunk is larger than capacity, only the newest tail that fits is kept.
If output request is larger than current length, the call returns only what is available.

Single-element enqueue/dequeue are still useful for control logic and tests, but batch calls are the fast path for streaming data.

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.
enqueue_slice()/dequeue_slice(): Preferred bulk API for steady-state data transfer.
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.1