irtt_client/lib.rs
1//! Reusable client/session/event layer for IRTT-compatible probes.
2//!
3//! `irtt-client` opens IRTT-compatible sessions, sends echo probes, receives
4//! replies, classifies loss/late/duplicate packets, and emits [`ClientEvent`]
5//! values for callers to consume directly or aggregate with `irtt-stats`.
6//! With the `tokio` feature enabled, `AsyncClient` provides the same low-level
7//! lifecycle for callers that own a Tokio runtime and drive readiness directly.
8//!
9//! Timing values intentionally preserve signed measurement semantics. When
10//! server timing is available, [`RttSample::effective`] is adjusted for server
11//! processing and can be negative if the reported server processing time exceeds
12//! the raw client-observed RTT. Directional [`OneWayDelaySample`] values are
13//! also signed when the required wall-clock timestamps are available; negative
14//! values usually indicate client/server clock skew.
15//!
16//! [`Client`] is the runtime-free low-level blocking adapter and requires no
17//! Tokio dependency at all; it is what a caller without a runtime, or that
18//! wants full control over its own event loop, should start from. With the
19//! `tokio` feature, `AsyncClient` provides the corresponding low-level Tokio
20//! adapter for a caller that owns a runtime and drives socket readiness
21//! itself. [`managed`] sits above both: `ManagedClientTask` /
22//! `ManagedClientHandle` (`tokio` feature) run and control one or more
23//! targets under a Tokio runtime, and `BlockingManagedClient` (`tokio`
24//! feature) wraps that in a synchronous owner backed by its own dedicated
25//! current-thread runtime for callers that want managed multi-target
26//! behavior without touching Tokio themselves.
27//!
28//! See `examples/` in the repository for a runnable example of each tier.
29//!
30#![forbid(unsafe_code)]
31
32#[cfg(feature = "tokio")]
33mod async_client;
34mod client;
35mod config;
36mod error;
37mod event;
38pub mod managed;
39mod metadata;
40mod probe;
41mod receive;
42mod session;
43mod socket;
44mod socket_options;
45mod timing;
46
47#[cfg(feature = "tokio")]
48pub use async_client::AsyncClient;
49pub use client::Client;
50pub use config::{
51 ClientAuthConfig, ClientConfig, NegotiationPolicy, RecvBudget, RunMode, SocketConfig,
52 MAX_DSCP_CODEPOINT, MAX_SERVER_FILL_BYTES, MAX_TTL, MAX_UDP_PAYLOAD_LENGTH,
53};
54pub use error::ClientError;
55pub use event::{
56 ClientEvent, OneWayDelaySample, OpenOutcome, PacketMeta, ReceivedStatsSample, RttSample,
57 ServerTiming, SignedDuration, WarningKind,
58};
59pub use session::{NegotiatedParams, NegotiationRestriction};
60pub use timing::ClientTimestamp;