base_scheduler/
frozen_buffer.rs

1// Released under the MIT License.
2// Copyright, 2026, by Samuel Williams.
3
4use crate::{BufferSlice, IoBuf, heap_buffer_pool::Slab};
5use std::{
6    ops::{Range, RangeBounds},
7    ptr::NonNull,
8};
9
10/// An immutable pool-backed chunk. Cloning or retaining a range shares its existing allocation; the final view returns the slot to the pool. Views keep the backing slab alive even after the pool is dropped, so parsers may choose to copy unusually long-lived fragments.
11pub struct FrozenBuffer {
12    slab: NonNull<Slab>,
13    index: usize,
14    range: Range<usize>,
15}
16impl FrozenBuffer {
17    pub(crate) fn new(slab: NonNull<Slab>, index: usize, range: Range<usize>) -> Self {
18        Self { slab, index, range }
19    }
20
21    /// Retain an independently owned range without copying payload bytes or allocating a reference-count wrapper.
22    pub fn view(&self, range: impl RangeBounds<usize>) -> BufferSlice<Self> {
23        self.clone().slice(range)
24    }
25}
26impl Clone for FrozenBuffer {
27    fn clone(&self) -> Self {
28        // SAFETY: All views retain the slot's one persistent slab claim together.
29        unsafe { self.slab.as_ref() }.retain(self.index);
30        Self::new(self.slab, self.index, self.range.clone())
31    }
32}
33impl AsRef<[u8]> for FrozenBuffer {
34    fn as_ref(&self) -> &[u8] {
35        // SAFETY: Every view retains the slot's reader count and persistent slab claim. No mutable lease can exist until the final view releases it.
36        unsafe {
37            std::slice::from_raw_parts(
38                self.slab.as_ref().pointer(self.index).add(self.range.start),
39                self.range.len(),
40            )
41        }
42    }
43}
44impl Drop for FrozenBuffer {
45    fn drop(&mut self) {
46        // SAFETY: Drop consumes this reader; the final reader returns the slot claim.
47        unsafe { Slab::release_reader(self.slab, self.index) };
48    }
49}
50// SAFETY: Shared views expose only immutable initialized bytes at a stable allocation and range, retained through the last view's release.
51unsafe impl IoBuf for FrozenBuffer {}
52
53// SAFETY: Shared views keep the slab alive and expose only immutable initialized bytes.
54unsafe impl Send for FrozenBuffer {}
55unsafe impl Sync for FrozenBuffer {}
56
57impl std::fmt::Debug for FrozenBuffer {
58    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
59        formatter
60            .debug_struct("FrozenBuffer")
61            .field("length", &self.range.len())
62            .finish_non_exhaustive()
63    }
64}
base_scheduler/frozen_buffer.rs

base_scheduler/
frozen_buffer.rs
