base_scheduler/
buffer_pooling.rs

1// Released under the MIT License.
2// Copyright, 2026, by Samuel Williams.
3
4use crate::{BufferPool, BufferPoolOptions};
5use std::io;
6
7/// Construct a backend-selected pool with portable ownership semantics. Applications choose the payload budget and alignment; implementations choose allocation and registration strategy. Pool construction performs no I/O on application resources.
8///
9/// `options.buffers` is the exact shared payload capacity, independent of worker count. Clones use that same budget. Internal worker caches must make returned capacity available to acquisitions on other workers; they must not silently partition the pool or multiply its capacity. Receivers and accepted I/O may retain slots, including while idle, so use a separate pool for independently required scratch storage.
10///
11/// Pools may retain backend resources for registration lifetime, but bound handles select their scheduler at construction and receive cancellation per operation. Backends document instance affinity and reject incompatible resources before submitting I/O. Closing a scheduler does not invalidate completed buffers or their retained views.
12///
13/// ```
14/// use base_scheduler::{BufferPoolOptions, BufferPooling, Cancellation, IoBuf,
15///     OperationResult, ReceiveBuffer, SocketPacketReading, SocketPacketReader, SocketRecvMessage};
16///
17/// async fn receive<S: SocketPacketReading>(scheduler: &S, socket: &S::Socket,
18///     cancellation: &Cancellation) -> OperationResult<()>
19/// where S::Socket: 'static {
20///     let pool = scheduler.buffer_pool(BufferPoolOptions::new(128, 64 * 1024))?;
21///     let mut reader = scheduler.socket_packet_reader_with_pool(socket, pool)?;
22///     let received = reader.read(cancellation).await;
23///     reader.close().await?;
24///     drop(reader);
25///     if let Some(message) = received? {
26///         let frozen = message.into_payload().freeze();
27///         let frame = frozen.clone().slice(..);
28///         drop((frame, frozen));
29///     }
30///     Ok(())
31/// }
32/// ```
33pub trait BufferPooling {
34    /// The pool type constructed by [`buffer_pool`](Self::buffer_pool).
35    type Pool: BufferPool;
36    /// Construct a pool satisfying `options`, or return an error if the backend cannot.
37    fn buffer_pool(&self, options: BufferPoolOptions) -> io::Result<Self::Pool>;
38}
base_scheduler/buffer_pooling.rs

base_scheduler/
buffer_pooling.rs
