base_scheduler/
buffer_pool.rs

1// Released under the MIT License.
2// Copyright, 2026, by Samuel Williams.
3
4use crate::{Cancellation, Cancelled, ReceiveBuffer};
5use std::future::Future;
6
7/// A bounded, shareable source of exclusively writable, stable receive storage. Clones share the same capacity. Completed buffers and their frozen views retain storage independently of pool handles, receivers, and polling threads; the final owner makes that slot reusable.
8///
9/// Published receive buffers count against capacity, including while an accepted receive is idle. Use a separate pool for independently required scratch buffers or file pipelines. The scheduler's portable factory supplies a shared total budget; concrete backend experiments may document a different capacity distribution.
10///
11/// Acquisition returns a fully initialized `buffer_size()` prefix with at least `alignment()` alignment. Its previous contents are unspecified. Exhaustion waits with cancellation instead of growing the pool. Retained views and accepted I/O count against capacity until their access retires, including after future abandonment. Kernel registration and publication are implementation details; neither may grant concurrent access to a leased buffer.
12pub trait BufferPool: Clone + Send + Sync + 'static {
13    type Buffer: ReceiveBuffer;
14
15    /// Total slot capacity, including leased and published buffers, rather than the number currently free. Worker-local caches are part of this total.
16    fn capacity(&self) -> usize;
17    fn buffer_size(&self) -> usize;
18    fn alignment(&self) -> usize;
19
20    /// Acquire immediately, or return `None` without waiting for capacity.
21    fn try_acquire(&self) -> Option<Self::Buffer>;
22
23    /// Pre-cancellation leaves capacity unchanged. Acquisition wins a subsequent cancellation race. Dropping or forgetting a pending acquisition must not release storage still accessible by another owner.
24    fn acquire(
25        &self,
26        cancellation: &Cancellation,
27    ) -> impl Future<Output = Result<Self::Buffer, Cancelled>> + Send;
28}
base_scheduler/buffer_pool.rs

base_scheduler/
buffer_pool.rs
