base_scheduler/
lib.rs

1// Released under the MIT License.
2// Copyright, 2026, by Samuel Williams.
3
4//! Explicit, runtime-independent scheduler capabilities for protocol libraries.
5//!
6//! Applications choose an execution environment; libraries ask for the operations they need. This crate defines the interface and runtime-independent support such as [`Cancellation`] and [`HeapBufferPool`]. It contains no executor, reactor, operating-system I/O implementation, or runtime adapter; companion crates such as `base-scheduler-direct`, `base-scheduler-tokio`, and `base-scheduler-native` provide those.
7//!
8//! # Socket and file I/O
9//!
10//! Construct a handle from the scheduler once, then pass a [`Cancellation`] to each operation. A handle keeps its scheduler for its whole lifetime, and protocol code can retain it alongside parser state.
11//!
12//! | Factory | Handle | Operations |
13//! | --- | --- | --- |
14//! | [`SocketStreamReading`] | [`SocketStreamReader`] | `read` returns an owned chunk; `read_into` and `read_vectored` use borrowed parser storage. |
15//! | [`SocketStreamWriting`] | [`SocketStreamWriter`] | `write` and `write_vectored` make borrowed transfers; `submit` accepts owned output that progresses independently, and `flush` waits for all accepted bytes. |
16//! | [`SocketPacketReading`] | [`SocketPacketReader`] | `read` returns an owned message with source metadata; borrowed forms fill caller storage and report truncation. |
17//! | [`SocketPacketWriting`] | [`SocketPacketWriter`] | Send one packet from borrowed scalar/vector storage or an owned buffer, with an optional destination. |
18//! | [`FileReading`] | [`FileReader`] | Owned-buffer `read` at the OS cursor, or `read_at` an explicit offset. |
19//! | [`FileWriting`] | [`FileWriter`] | Owned-buffer `write` at the OS cursor, `write_at` an explicit offset, or `write_all`. |
20//!
21//! Use one handle per sequential execution, with separate readers and writers for concurrent tasks. Borrowed-only readers allocate no receive pool; owned reads initialize a default pool lazily, or use a shared [`BufferPool`] passed to `socket_stream_reader_with_pool` or `socket_packet_reader_with_pool`. Retained chunks can [`freeze`](ReceiveBuffer::freeze) into immutable views that move between tasks. File handles have no private logical position, and file operations return the original buffer owner alongside the [`BufferResult`].
22//!
23//! Call `close().await` on each handle before dropping it and exclusively closing its resource, flushing successful stream output first. Dropping a handle is not an awaited cleanup barrier.
24//!
25//! # Other capabilities
26//!
27//! Protocol libraries require the individual capabilities they use; there is no universal scheduler trait. Socket and file lifecycle operations are separate capabilities, such as [`SocketOpen`], [`SocketBind`], [`SocketListen`], [`SocketConnect`], [`SocketAccept`], [`FileOpen`], [`FileStat`], [`FileSync`], [`SocketClose`], and [`FileClose`].
28//!
29//! | Capability | Contract |
30//! | --- | --- |
31//! | [`Clock`] | Monotonic observations, cancellable relative or absolute waits, and operation timeouts. |
32//! | [`Timers`] | Experimental reusable timer state for repeated deadline waits. |
33//! | [`Spawn`] | Task dispatch with implementation-associated, owning completion handles. |
34//! | [`Blocking`] | Bounded admission of owned synchronous work. |
35//! | [`ProcessWait`] | Individual child and Unix process-group status waits with cooperative cancellation. |
36//! | `PipeReading`, `PipeWriting` | Unix adoption of owned pipe descriptors, such as child process standard streams, as sequential readers and writers. |
37//! | [`Signals`] | Notification subscriptions with implementation-associated guards and signal identifiers. |
38//! | [`BufferPooling`] | Shareable bounded storage with retained immutable views and cancellable capacity waits. |
39//! | Extensions | Typed socket options ([`SocketGetOption`], [`SocketSetOption`]), [`AddressResolution`], [`SocketRegistration`], [`FileAdvice`], and [`FileAllocate`]. |
40//!
41//! Operation futures use static dispatch and are `Send`; no boxed future or runtime-selection feature is required. Spawned futures and outputs are `Send + 'static`.
42//!
43//! [`Cancellation`] is a cooperative signal: clones share state, children inherit ancestor cancellation, and dropping a signal does not cancel it. Pre-cancellation prevents submission, successful progress can win a concurrent request, and cancellation does not roll back transferred bytes or cursor changes. A task handle owns its execution: await it to observe completion, or drop it to request destruction after any active poll returns. Keep the scheduler and its drivers alive while accepted work retires.
44//!
45//! See the [I/O usage guide](https://github.com/base-rs/base-scheduler/blob/main/context/io.md), [interface reference](https://github.com/base-rs/base-scheduler/blob/main/context/interface.md), [design and behavioral contracts](https://github.com/base-rs/base-scheduler/blob/main/context/design.md), and [runnable examples](https://github.com/base-rs/base-scheduler/blob/main/examples/readme.md).
46#![deny(unsafe_op_in_unsafe_fn)]
47#![warn(missing_docs)]
48
49mod address_hints;
50mod address_info;
51mod address_info_collection;
52mod address_info_view;
53mod address_resolution;
54mod address_resolve_error;
55mod address_resolve_error_kind;
56mod address_service;
57mod advice_mode;
58mod allocation_mode;
59mod blocking;
60mod blocking_error;
61mod buffer_lease;
62mod buffer_pool;
63mod buffer_pool_options;
64mod buffer_pooling;
65mod buffer_result;
66mod buffer_sequence_owner;
67mod buffer_slice;
68mod cancellation;
69mod cancelled;
70mod clock;
71mod defer_cancel;
72mod file_advice;
73mod file_allocate;
74mod file_close;
75mod file_metadata;
76mod file_open;
77mod file_operation;
78mod file_options;
79mod file_reader;
80mod file_reading;
81mod file_seek;
82mod file_stat;
83mod file_sync;
84mod file_truncate;
85mod file_type;
86mod file_writer;
87mod file_writing;
88mod frozen_buffer;
89mod heap_buffer_pool;
90mod io_buf;
91mod io_buf_mut;
92mod io_buf_sequence;
93mod io_buf_sequence_mut;
94mod io_buffers;
95mod io_buffers_mut;
96mod notify;
97mod operation_error;
98mod owned_socket_recv_message;
99#[cfg(unix)]
100mod pipe_reader;
101#[cfg(unix)]
102mod pipe_reading;
103#[cfg(unix)]
104mod pipe_writer;
105#[cfg(unix)]
106mod pipe_writing;
107mod process_wait;
108mod process_wait_flags;
109mod process_wait_result;
110mod receive_buffer;
111mod signals;
112mod socket_accept;
113mod socket_address_view;
114mod socket_bind;
115mod socket_close;
116mod socket_connect;
117mod socket_domain;
118mod socket_get_option;
119mod socket_keepalive;
120mod socket_listen;
121mod socket_local_address;
122mod socket_open;
123mod socket_operation;
124mod socket_option;
125mod socket_options;
126mod socket_packet_reader;
127mod socket_packet_reading;
128mod socket_packet_writer;
129mod socket_packet_writing;
130mod socket_peer_address;
131mod socket_protocol;
132mod socket_recv_flags;
133mod socket_recv_message;
134mod socket_recv_message_mut;
135mod socket_recv_result;
136mod socket_registration;
137mod socket_reuse_address;
138mod socket_send_flags;
139mod socket_set_option;
140mod socket_shutdown;
141mod socket_stream_reader;
142mod socket_stream_reading;
143mod socket_stream_writer;
144mod socket_stream_writing;
145mod socket_type;
146mod spawn;
147mod spawn_error;
148mod sync_mode;
149mod task_error;
150mod tcp_no_delay;
151mod timeout_error;
152mod timers;
153
154pub use address_hints::AddressHints;
155pub use address_info::AddressInfo;
156pub use address_info_collection::AddressInfoCollection;
157pub use address_info_view::AddressInfoView;
158pub use address_resolution::AddressResolution;
159pub use address_resolve_error::AddressResolveError;
160pub use address_resolve_error_kind::AddressResolveErrorKind;
161pub use address_service::AddressService;
162pub use advice_mode::AdviceMode;
163pub use allocation_mode::AllocationMode;
164pub use blocking::Blocking;
165pub use blocking_error::BlockingError;
166pub use buffer_lease::BufferLease;
167pub use buffer_pool::BufferPool;
168pub use buffer_pool_options::BufferPoolOptions;
169pub use buffer_pooling::BufferPooling;
170pub use buffer_result::BufferResult;
171pub use buffer_slice::BufferSlice;
172pub use cancellation::Cancellation;
173pub use cancelled::Cancelled;
174pub use clock::Clock;
175pub use defer_cancel::defer_cancel;
176pub use file_advice::FileAdvice;
177pub use file_allocate::FileAllocate;
178pub use file_close::FileClose;
179pub use file_metadata::FileMetadata;
180pub use file_open::FileOpen;
181pub use file_operation::FileOperation;
182pub use file_options::FileOptions;
183pub use file_reader::FileReader;
184pub use file_reading::FileReading;
185pub use file_seek::FileSeek;
186pub use file_stat::FileStat;
187pub use file_sync::FileSync;
188pub use file_truncate::FileTruncate;
189pub use file_type::FileType;
190pub use file_writer::FileWriter;
191pub use file_writing::FileWriting;
192pub use frozen_buffer::FrozenBuffer;
193pub use heap_buffer_pool::HeapBufferPool;
194pub use io_buf::IoBuf;
195pub use io_buf_mut::IoBufMut;
196pub use io_buf_sequence::IoBufSequence;
197pub use io_buf_sequence_mut::IoBufSequenceMut;
198pub use io_buffers::IoBuffers;
199pub use io_buffers_mut::IoBuffersMut;
200pub use notify::Notify;
201pub use operation_error::{OperationError, OperationResult};
202pub use owned_socket_recv_message::OwnedSocketRecvMessage;
203#[cfg(unix)]
204pub use pipe_reader::PipeReader;
205#[cfg(unix)]
206pub use pipe_reading::PipeReading;
207#[cfg(unix)]
208pub use pipe_writer::PipeWriter;
209#[cfg(unix)]
210pub use pipe_writing::PipeWriting;
211pub use process_wait::ProcessWait;
212pub use process_wait_flags::ProcessWaitFlags;
213pub use process_wait_result::ProcessWaitResult;
214pub use receive_buffer::ReceiveBuffer;
215pub use signals::Signals;
216pub use socket_accept::SocketAccept;
217pub use socket_address_view::SocketAddressView;
218pub use socket_bind::SocketBind;
219pub use socket_close::SocketClose;
220pub use socket_connect::SocketConnect;
221pub use socket_domain::SocketDomain;
222pub use socket_get_option::SocketGetOption;
223pub use socket_keepalive::SocketKeepalive;
224pub use socket_listen::SocketListen;
225pub use socket_local_address::SocketLocalAddress;
226pub use socket_open::SocketOpen;
227pub use socket_operation::SocketOperation;
228pub use socket_option::SocketOption;
229pub use socket_options::SocketOptions;
230pub use socket_packet_reader::SocketPacketReader;
231pub use socket_packet_reading::SocketPacketReading;
232pub use socket_packet_writer::SocketPacketWriter;
233pub use socket_packet_writing::SocketPacketWriting;
234pub use socket_peer_address::SocketPeerAddress;
235pub use socket_protocol::SocketProtocol;
236pub use socket_recv_flags::SocketRecvFlags;
237pub use socket_recv_message::SocketRecvMessage;
238pub use socket_recv_message_mut::SocketRecvMessageMut;
239pub use socket_recv_result::SocketRecvResult;
240pub use socket_registration::SocketRegistration;
241pub use socket_reuse_address::SocketReuseAddress;
242pub use socket_send_flags::SocketSendFlags;
243pub use socket_set_option::SocketSetOption;
244pub use socket_shutdown::SocketShutdown;
245pub use socket_stream_reader::SocketStreamReader;
246pub use socket_stream_reading::SocketStreamReading;
247pub use socket_stream_writer::SocketStreamWriter;
248pub use socket_stream_writing::SocketStreamWriting;
249pub use socket_type::SocketType;
250pub use spawn::Spawn;
251pub use spawn_error::SpawnError;
252pub use sync_mode::SyncMode;
253pub use task_error::TaskError;
254pub use tcp_no_delay::TcpNoDelay;
255pub use timeout_error::TimeoutError;
256pub use timers::Timers;
257
258/// An IP endpoint, compatible with standard-library socket addresses.
259pub use std::net::SocketAddr as SocketAddress;
260
261/// Compiles and runs the readme examples as doctests.
262#[cfg(doctest)]
263#[doc = include_str!("../readme.md")]
264pub struct ReadmeDoctests;
base_scheduler/lib.rs

base_scheduler/
lib.rs
