minip2p_platform/lib.rs
1//! Portable platform contracts for minip2p.
2//!
3//! Every agent, transport, and runtime in minip2p is caller-driven: it never
4//! reads a system clock and never draws randomness on its own. Instead the host
5//! samples time once per drive iteration and passes the resulting [`Now`] to
6//! everything it drives, and supplies an [`EntropySource`] to the components
7//! that need randomness.
8//!
9//! This crate holds those contracts, plus the [`Deadline`] type that
10//! caller-driven components use to report when they next need attention. It is
11//! `no_std` + `alloc` compatible and has no networking code; the `std` feature
12//! adds [`StdClock`] and [`StdEntropy`] for hosted platforms.
13//!
14//! # Example
15//!
16//! ```
17//! use minip2p_platform::{Clock, Deadline, Now};
18//!
19//! struct Agent {
20//! fire_at: Deadline,
21//! }
22//!
23//! impl Agent {
24//! // The agent is told what time it is; it never asks.
25//! fn poll(&mut self, now: Now) -> bool {
26//! self.fire_at.is_expired_at(now)
27//! }
28//!
29//! fn next_deadline(&self) -> Option<Deadline> {
30//! Some(self.fire_at)
31//! }
32//! }
33//!
34//! # #[cfg(feature = "std")]
35//! # {
36//! use minip2p_platform::StdClock;
37//!
38//! let mut clock = StdClock::new();
39//! let mut agent = Agent {
40//! fire_at: Deadline::from_millis(0),
41//! };
42//!
43//! // One clock sample drives everything in this iteration.
44//! let now = clock.now();
45//! assert!(agent.poll(now));
46//! # }
47//! ```
48#![cfg_attr(not(feature = "std"), no_std)]
49
50extern crate alloc;
51
52mod clock;
53mod deadline;
54mod entropy;
55
56#[cfg(feature = "std")]
57mod std_impl;
58
59pub use clock::{Clock, Now};
60pub use deadline::Deadline;
61pub use entropy::{EntropyError, EntropySource, SharedEntropy};
62
63#[cfg(feature = "std")]
64pub use std_impl::{StdClock, StdEntropy};