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    /// The exclusively writable receive storage returned by acquisition.
14    type Buffer: ReceiveBuffer;
15
16    /// Total slot capacity, including leased and published buffers, rather than the number currently free. Worker-local caches are part of this total.
17    fn capacity(&self) -> usize;
18    /// The initialized length, in bytes, of each acquired buffer.
19    fn buffer_size(&self) -> usize;
20    /// The minimum alignment, in bytes, of each acquired buffer's first byte.
21    fn alignment(&self) -> usize;
22
23    /// Acquire immediately, or return `None` without waiting for capacity.
24    fn try_acquire(&self) -> Option<Self::Buffer>;
25
26    /// 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.
27    fn acquire(
28        &self,
29        cancellation: &Cancellation,
30    ) -> impl Future<Output = Result<Self::Buffer, Cancelled>> + Send;
31}
base_scheduler/buffer_pool.rs

base_scheduler/
buffer_pool.rs
