Skip to main content

Crate refraction_types

Crate refraction_types 

Source
Expand description

§refraction-types

A zero-dependency, fixed-capacity ring buffer for networking and protocol parsing.

This crate centers around [BoundedRingBuffer<T>], a bounded queue with overwrite-on-full semantics and a byte-oriented API for network payloads.

§Why This Exists

This crate was extracted from transport-layer and Redis-like data flow work. The goal was to have a simple, fast, dependency-free structure tuned for network transmission and buffered data handling. Existing crates did not provide enough control over flow behavior, so this crate was split out to be reusable across future projects and to evolve into something more general.

§Why This Crate

  • Deterministic memory usage: capacity is fixed at construction time.
  • Predictable behavior under pressure: newest writes are kept, oldest data is dropped.
  • Fast typed reads/writes on u8 buffers for frame/header parsing.
  • No external runtime dependencies.

§Core Semantics

  • [BoundedRingBuffer::enqueue] pushes one element to the tail.
  • [BoundedRingBuffer::dequeue] pops one element from the head.
  • If full, enqueue advances the head first (oldest item is discarded).
  • [BoundedRingBuffer::front] returns the oldest readable element.
  • [BoundedRingBuffer::back] returns the newest written element.
  • [BoundedRingBuffer::advance] reserves/advances write position by n slots and applies the same overwrite semantics.

§Quick Start

use refraction_types::ring_buffer::BoundedRingBuffer;

let mut rb = BoundedRingBuffer::<u8>::with_capacity(4);
rb.enqueue(10);
rb.enqueue(20);
rb.enqueue(30);

assert_eq!(rb.front(), Some(&10));
assert_eq!(rb.back(), Some(&30));
assert_eq!(rb.dequeue(), Some(10));
assert_eq!(rb.len(), 2);

§Overwrite-On-Full Example

use refraction_types::ring_buffer::BoundedRingBuffer;

let mut rb = BoundedRingBuffer::<u8>::with_capacity(3);
rb.enqueue_slice(&[1, 2, 3]);
rb.enqueue(4); // overwrites 1

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

§Typed Byte API (BoundedRingBuffer<u8>)

BoundedRingBuffer<u8> exposes methods like enqueue_u16, peek_i64, and dequeue_f32. All numeric conversions use big-endian representation.

use refraction_types::ring_buffer::BoundedRingBuffer;

let mut rb = BoundedRingBuffer::<u8>::with_capacity(16);
rb.enqueue_u16(0xCAFE);
rb.enqueue_i32(-7);

assert_eq!(rb.peek_u16(), Some(0xCAFE));
assert_eq!(rb.dequeue_u16(), Some(0xCAFE));
assert_eq!(rb.dequeue_i32(), Some(-7));

§Iteration

Use [BoundedRingBuffer::iter] and [BoundedRingBuffer::iter_mut] to traverse readable elements in logical queue order, regardless of internal wrap-around.

§Modules

§Notes

  • T must implement Copy + Default.
  • with_capacity(0) panics by design.
  • dequeue_slice panics if output buffer is smaller than requested dequeue size.

Modules§

ring_buffer
ring_iter
ring_specialization
Numeric specializations for BoundedRingBuffer<u8>.
ring_traits

Constants§

BOUNDED_RING_BUFFER_DEFAULT_SIZE
Default capacity used by ring_buffer::BoundedRingBuffer::new.