1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
// Released under the MIT License.
// Copyright, 2026, by Samuel Williams.
use crate::{FrozenBuffer, IoBuf, IoBufMut, heap_buffer_pool::Slab};
use std::{ops::Range, ptr::NonNull, sync::atomic::Ordering};
/// An exclusive writable pool lease. Its initialized length can be shortened after a read, without copying or borrowing the receiver. Drop returns storage to the pool; an I/O backend must retain this owner until its access retires. A lease keeps its backing slab alive even after the pool is dropped.
pub struct BufferLease {
slab: Option<NonNull<Slab>>,
index: usize,
length: usize,
}
impl BufferLease {
pub(crate) fn new(slab: NonNull<Slab>, index: usize, length: usize) -> Self {
Self {
slab: Some(slab),
index,
length,
}
}
/// Limit the visible initialized prefix. Panics if the requested length exceeds the current prefix.
pub fn truncate(&mut self, length: usize) {
assert!(length <= self.length, "buffer length out of bounds");
self.length = length;
}
/// Transfer this lease into immutable, independently retainable storage. No allocation or payload copy is required.
pub fn freeze(mut self) -> FrozenBuffer {
let slab = self.slab.take().unwrap();
// SAFETY: This lease owns the slot's persistent slab claim.
unsafe { slab.as_ref() }.slots[self.index]
.readers
.store(1, Ordering::Relaxed);
FrozenBuffer::new(
slab,
self.index,
Range {
start: 0,
end: self.length,
},
)
}
}
impl AsRef<[u8]> for BufferLease {
fn as_ref(&self) -> &[u8] {
// SAFETY: This lease owns its slot's persistent slab claim; the allocation and initialized prefix remain stable until release.
let slab = unsafe { self.slab.unwrap().as_ref() };
unsafe { std::slice::from_raw_parts(slab.pointer(self.index), self.length) }
}
}
impl AsMut<[u8]> for BufferLease {
fn as_mut(&mut self) -> &mut [u8] {
// SAFETY: The unique lease and exclusive borrow prevent other accesses to this slot. Frozen views cannot coexist with a mutable lease.
let slab = unsafe { self.slab.unwrap().as_ref() };
unsafe { std::slice::from_raw_parts_mut(slab.pointer(self.index), self.length) }
}
}
impl Drop for BufferLease {
fn drop(&mut self) {
if let Some(slab) = self.slab.take() {
// SAFETY: Drop consumes the unique mutable slot claim.
unsafe { Slab::release(slab, self.index) };
}
}
}
// SAFETY: Pool storage is initialized, fixed in size, and stable as its exclusive lease moves. Only the owned lease permits mutation; operations retain it through retirement.
unsafe impl IoBuf for BufferLease {}
unsafe impl IoBufMut for BufferLease {}
// SAFETY: The owned slot claim keeps the slab alive, and only an exclusive borrow permits writes.
unsafe impl Send for BufferLease {}
unsafe impl Sync for BufferLease {}
impl std::fmt::Debug for BufferLease {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("BufferLease")
.field("length", &self.length)
.finish_non_exhaustive()
}
}
impl crate::ReceiveBuffer for BufferLease {
type Frozen = FrozenBuffer;
fn truncate(&mut self, length: usize) {
BufferLease::truncate(self, length);
}
fn freeze(self) -> FrozenBuffer {
BufferLease::freeze(self)
}
}