Nils Andreas Svee
56a2a653d0
Each published crate (irtt-rs, irtt-client, irtt-server, irtt-stats, irtt-proto) now points crates.io at its own README instead of inheriting the root project README via the workspace-wide readme default, which is removed. Each crate README is a short landing page: what the crate is, who should use it, which sibling crate to use instead if this isn't the right abstraction level, and links to docs.rs and the main repository. Add real Cargo example targets teaching irtt-client's blocking/Tokio/ managed API tiers, a basic and a multi-listener irtt-server example, and an irtt-stats example contrasting finite vs continuous retention. irtt-proto intentionally has none. Update each crate's top-level rustdoc to explain its API-tier choices and point at the examples, and enable docs.rs rustdoc example scraping for irtt-client and irtt-server (via doc-scrape-examples on each example target, needed because the crate has dev-dependencies). The client examples are caller-paced against next_send_deadline() rather than sending on every loop iteration, bound their receive wait by the next send/timeout deadline instead of awaiting indefinitely, poll timeouts on a short fixed cadence, and surface send/receive/close errors instead of discarding them via unwrap_or_default()/if-let-Ok -- so they demonstrate correct pacing and terminate/report cleanly rather than racing the server, hanging on a lost reply, or silently dropping a failed final close.
61 lines
2.5 KiB
Rust
61 lines
2.5 KiB
Rust
//! Reusable client/session/event layer for IRTT-compatible probes.
|
|
//!
|
|
//! `irtt-client` opens IRTT-compatible sessions, sends echo probes, receives
|
|
//! replies, classifies loss/late/duplicate packets, and emits [`ClientEvent`]
|
|
//! values for callers to consume directly or aggregate with `irtt-stats`.
|
|
//! With the `tokio` feature enabled, `AsyncClient` provides the same low-level
|
|
//! lifecycle for callers that own a Tokio runtime and drive readiness directly.
|
|
//!
|
|
//! Timing values intentionally preserve signed measurement semantics. When
|
|
//! server timing is available, [`RttSample::effective`] is adjusted for server
|
|
//! processing and can be negative if the reported server processing time exceeds
|
|
//! the raw client-observed RTT. Directional [`OneWayDelaySample`] values are
|
|
//! also signed when the required wall-clock timestamps are available; negative
|
|
//! values usually indicate client/server clock skew.
|
|
//!
|
|
//! [`Client`] is the runtime-free low-level blocking adapter and requires no
|
|
//! Tokio dependency at all; it is what a caller without a runtime, or that
|
|
//! wants full control over its own event loop, should start from. With the
|
|
//! `tokio` feature, `AsyncClient` provides the corresponding low-level Tokio
|
|
//! adapter for a caller that owns a runtime and drives socket readiness
|
|
//! itself. [`managed`] sits above both: `ManagedClientTask` /
|
|
//! `ManagedClientHandle` (`tokio` feature) run and control one or more
|
|
//! targets under a Tokio runtime, and `BlockingManagedClient` (`tokio`
|
|
//! feature) wraps that in a synchronous owner backed by its own dedicated
|
|
//! current-thread runtime for callers that want managed multi-target
|
|
//! behavior without touching Tokio themselves.
|
|
//!
|
|
//! See `examples/` in the repository for a runnable example of each tier.
|
|
//!
|
|
#![forbid(unsafe_code)]
|
|
|
|
#[cfg(feature = "tokio")]
|
|
mod async_client;
|
|
mod client;
|
|
mod config;
|
|
mod error;
|
|
mod event;
|
|
pub mod managed;
|
|
mod metadata;
|
|
mod probe;
|
|
mod receive;
|
|
mod session;
|
|
mod socket;
|
|
mod socket_options;
|
|
mod timing;
|
|
|
|
#[cfg(feature = "tokio")]
|
|
pub use async_client::AsyncClient;
|
|
pub use client::Client;
|
|
pub use config::{
|
|
ClientAuthConfig, ClientConfig, NegotiationPolicy, RecvBudget, RunMode, SocketConfig,
|
|
MAX_DSCP_CODEPOINT, MAX_SERVER_FILL_BYTES, MAX_TTL, MAX_UDP_PAYLOAD_LENGTH,
|
|
};
|
|
pub use error::ClientError;
|
|
pub use event::{
|
|
ClientEvent, OneWayDelaySample, OpenOutcome, PacketMeta, ReceivedStatsSample, RttSample,
|
|
ServerTiming, SignedDuration, WarningKind,
|
|
};
|
|
pub use session::{NegotiatedParams, NegotiationRestriction};
|
|
pub use timing::ClientTimestamp;
|