refraction_types/lib.rs
1//! # refraction-types
2//!
3//! A zero-dependency, fixed-capacity ring buffer for networking and protocol parsing.
4//!
5//! This crate centers around [`BoundedRingBuffer<T>`], a bounded queue with
6//! overwrite-on-full semantics and a byte-oriented API for network payloads.
7//!
8//! ## Why This Exists
9//!
10//! This crate was extracted from transport-layer and Redis-like data flow work.
11//! The goal was to have a simple, fast, dependency-free structure tuned for
12//! network transmission and buffered data handling. Existing crates did not
13//! provide enough control over flow behavior, so this crate was split out to be
14//! reusable across future projects and to evolve into something more general.
15//!
16//! ## Why This Crate
17//!
18//! - Deterministic memory usage: capacity is fixed at construction time.
19//! - Predictable behavior under pressure: newest writes are kept, oldest data is dropped.
20//! - Primary batch data path via [`BoundedRingBuffer::enqueue_slice`] and
21//! [`BoundedRingBuffer::dequeue_slice`].
22//! - Fast typed reads/writes on `u8` buffers for frame/header parsing.
23//! - No external runtime dependencies.
24//!
25//! ## Core Semantics
26//!
27//! - [`BoundedRingBuffer::enqueue`] pushes one element to the tail.
28//! - [`BoundedRingBuffer::dequeue`] pops one element from the head.
29//! - [`BoundedRingBuffer::enqueue_slice`] and [`BoundedRingBuffer::dequeue_slice`]
30//! are the preferred APIs for chunked transport I/O.
31//! - If full, `enqueue` advances the head first (oldest item is discarded).
32//! - [`BoundedRingBuffer::front`] returns the oldest readable element.
33//! - [`BoundedRingBuffer::back`] returns the newest written element.
34//! - [`BoundedRingBuffer::advance`] reserves/advances write position by `n` slots and
35//! applies the same overwrite semantics.
36//!
37//! ## Quick Start
38//!
39//! ```
40//! use refraction_types::ring_buffer::BoundedRingBuffer;
41//!
42//! let mut rb = BoundedRingBuffer::<u8>::with_capacity(4);
43//! rb.enqueue(10);
44//! rb.enqueue(20);
45//! rb.enqueue(30);
46//!
47//! assert_eq!(rb.front(), Some(&10));
48//! assert_eq!(rb.back(), Some(&30));
49//! assert_eq!(rb.dequeue(), Some(10));
50//! assert_eq!(rb.len(), 2);
51//! ```
52//!
53//! ## Overwrite-On-Full Example
54//!
55//! ```
56//! use refraction_types::ring_buffer::BoundedRingBuffer;
57//!
58//! let mut rb = BoundedRingBuffer::<u8>::with_capacity(3);
59//! rb.enqueue_slice(&[1, 2, 3]);
60//! rb.enqueue(4); // overwrites 1
61//!
62//! let mut out = [0_u8; 3];
63//! let read = rb.dequeue_slice(&mut out, 3);
64//! assert_eq!(read, 3);
65//! assert_eq!(out, [2, 3, 4]);
66//! ```
67//!
68//! ## Batch I/O Example (Primary Path)
69//!
70//! ```
71//! use refraction_types::ring_buffer::BoundedRingBuffer;
72//!
73//! let mut rb = BoundedRingBuffer::<u8>::with_capacity(8);
74//! rb.enqueue_slice(&[10, 11, 12, 13, 14]);
75//!
76//! let mut out = [0_u8; 3];
77//! let read = rb.dequeue_slice(&mut out, 3);
78//! assert_eq!(read, 3);
79//! assert_eq!(out, [10, 11, 12]);
80//! ```
81//!
82//! ## Typed Byte API (`BoundedRingBuffer<u8>`)
83//!
84//! `BoundedRingBuffer<u8>` exposes methods like `enqueue_u16`, `peek_i64`, and
85//! `dequeue_f32`. All numeric conversions use **big-endian** representation.
86//!
87//! ```
88//! use refraction_types::ring_buffer::BoundedRingBuffer;
89//!
90//! let mut rb = BoundedRingBuffer::<u8>::with_capacity(16);
91//! rb.enqueue_u16(0xCAFE);
92//! rb.enqueue_i32(-7);
93//!
94//! assert_eq!(rb.peek_u16(), Some(0xCAFE));
95//! assert_eq!(rb.dequeue_u16(), Some(0xCAFE));
96//! assert_eq!(rb.dequeue_i32(), Some(-7));
97//! ```
98//!
99//! ## Iteration
100//!
101//! Use [`BoundedRingBuffer::iter`] and [`BoundedRingBuffer::iter_mut`] to traverse
102//! readable elements in logical queue order, regardless of internal wrap-around.
103//!
104//! ## Modules
105//!
106//! - [`ring_buffer`]: core type and queue operations.
107//! - [`ring_specialization`]: typed big-endian helpers for `BoundedRingBuffer<u8>`.
108//! - [`ring_iter`]: iterator wrapper types.
109//! - [`ring_traits`]: trait implementations (`Display`, `Default`, `Extend`, etc.).
110//!
111//! ## Notes
112//!
113//! - `T` must implement `Copy + Default`.
114//! - `with_capacity(0)` panics by design.
115//! - `dequeue_slice` panics if output buffer is smaller than requested dequeue size.
116
117/// Default capacity used by [`ring_buffer::BoundedRingBuffer::new`].
118pub const BOUNDED_RING_BUFFER_DEFAULT_SIZE: usize = 65_535;
119
120pub mod ring_buffer;
121pub mod ring_iter;
122pub mod ring_specialization;
123pub mod ring_traits;
124
125#[cfg(test)]
126mod ring_test;