docs(crates): give each published crate its own crates.io README and examples
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.
This commit is contained in:
20 files changed
+751
-12
No files matched your search
@@ -7,7 +7,7 @@ license.workspace = true
|
||||
rust-version.workspace = true
|
||||
repository.workspace = true
|
||||
homepage.workspace = true
|
||||
readme.workspace = true
|
||||
readme = "README.md"
|
||||
keywords = ["irtt", "networking", "latency", "rtt"]
|
||||
categories = ["network-programming"]
|
||||
|
||||
@@ -27,6 +27,21 @@ tokio = ["dep:tokio"]
|
||||
|
||||
[package.metadata.docs.rs]
|
||||
all-features = true
|
||||
cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
|
||||
|
||||
[[example]]
|
||||
name = "blocking_client"
|
||||
doc-scrape-examples = true
|
||||
|
||||
[[example]]
|
||||
name = "tokio_client"
|
||||
required-features = ["tokio"]
|
||||
doc-scrape-examples = true
|
||||
|
||||
[[example]]
|
||||
name = "managed_client"
|
||||
required-features = ["tokio"]
|
||||
doc-scrape-examples = true
|
||||
|
||||
[dev-dependencies]
|
||||
irtt-server.workspace = true
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# irtt-client
|
||||
|
||||
Reusable client/session library for IRTT-compatible round-trip-time probing:
|
||||
socket lifecycle, open negotiation, probe send/receive, loss/duplicate/late
|
||||
classification, and a typed event stream.
|
||||
|
||||
## Looking for the CLI?
|
||||
|
||||
If you just want to run probes from the command line, use the
|
||||
[`irtt-rs`](https://crates.io/crates/irtt-rs) application package instead,
|
||||
which installs the `irtt-client` binary. This crate is the library the
|
||||
binaries are built on.
|
||||
|
||||
## API tiers
|
||||
|
||||
- `Client` — runtime-free blocking adapter. No Tokio dependency; this is the
|
||||
default build.
|
||||
- `AsyncClient` (feature `tokio`) — low-level Tokio adapter for callers that
|
||||
own a runtime and drive readiness directly.
|
||||
- `managed` (feature `tokio`) — a unified managed driver: `ManagedClientTask`
|
||||
/ `ManagedClientHandle` for multi-target orchestration under a Tokio
|
||||
runtime, and `BlockingManagedClient` for synchronous callers, which owns its
|
||||
own dedicated current-thread runtime.
|
||||
|
||||
Tokio stays optional: the default build has no runtime and no Tokio
|
||||
dependency at all.
|
||||
|
||||
See `examples/` in the repository for runnable examples of each tier.
|
||||
|
||||
## Documentation
|
||||
|
||||
Full API documentation is on [docs.rs/irtt-client](https://docs.rs/irtt-client).
|
||||
|
||||
## Project
|
||||
|
||||
Part of [irtt-rs](https://github.com/Lochnair/irtt-rs), an independent Rust
|
||||
implementation of an IRTT-compatible protocol stack.
|
||||
@@ -0,0 +1,110 @@
|
||||
//! Runtime-free blocking client example.
|
||||
//!
|
||||
//! Opens a session against a local IRTT-compatible server, sends a few
|
||||
//! probes, and prints the events observed. Uses only [`Client`], which has no
|
||||
//! Tokio dependency and works in a default (`--no-default-features`) build.
|
||||
//!
|
||||
//! Run a server first, then run this example:
|
||||
//!
|
||||
//! ```text
|
||||
//! cargo run -p irtt-rs --bin irtt-server --features server
|
||||
//! cargo run -p irtt-client --example blocking_client
|
||||
//! ```
|
||||
//!
|
||||
//! Without a reachable server this exits quickly with an open-timeout error
|
||||
//! instead of hanging, because the example shortens `open_timeouts` for a
|
||||
//! fast demonstration; a real caller would normally keep the default retry
|
||||
//! schedule.
|
||||
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use irtt_client::{Client, ClientConfig, ClientEvent};
|
||||
|
||||
const RUN_DURATION: Duration = Duration::from_secs(2);
|
||||
|
||||
fn main() {
|
||||
let config = ClientConfig {
|
||||
server_addr: "127.0.0.1:2112".to_owned(),
|
||||
duration: Some(RUN_DURATION),
|
||||
interval: Duration::from_millis(200),
|
||||
// A single short attempt keeps this example fast when no server is
|
||||
// reachable; production callers should generally keep the default.
|
||||
open_timeouts: vec![Duration::from_millis(300)],
|
||||
socket_config: irtt_client::SocketConfig {
|
||||
recv_timeout: Some(Duration::from_millis(100)),
|
||||
..Default::default()
|
||||
},
|
||||
..Default::default()
|
||||
};
|
||||
|
||||
let mut client = match Client::connect(config) {
|
||||
Ok(client) => client,
|
||||
Err(err) => {
|
||||
eprintln!("failed to prepare client socket: {err}");
|
||||
return;
|
||||
}
|
||||
};
|
||||
|
||||
match client.open() {
|
||||
Ok(outcome) => println!("session opened: {outcome:?}"),
|
||||
Err(err) => {
|
||||
eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
// The run itself lasts `duration`, but a lost probe isn't classified as
|
||||
// `EchoLoss` until `probe_timeout()` after it was sent; wait at least
|
||||
// that much past the run's own end so a loss near the end can still be
|
||||
// observed and printed before this example gives up and closes.
|
||||
let deadline = Instant::now() + RUN_DURATION + client.probe_timeout();
|
||||
while Instant::now() < deadline && !client.is_run_complete() {
|
||||
// send_probe is caller-paced: only call it once its own schedule
|
||||
// says a probe is due, rather than as fast as the loop spins.
|
||||
if client
|
||||
.next_send_deadline()
|
||||
.is_some_and(|send_at| Instant::now() >= send_at)
|
||||
{
|
||||
// A failed send retains its prepared probe without advancing the
|
||||
// schedule, so a persistent error (e.g. the interface going
|
||||
// down) would otherwise make this loop retry silently until the
|
||||
// safety deadline instead of reporting it.
|
||||
match client.send_probe() {
|
||||
Ok(events) => events.iter().for_each(print_event),
|
||||
Err(err) => {
|
||||
eprintln!("send failed: {err}");
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
match client.recv_once() {
|
||||
Ok(events) => events.iter().for_each(print_event),
|
||||
Err(err) => {
|
||||
eprintln!("receive failed: {err}");
|
||||
break;
|
||||
}
|
||||
}
|
||||
match client.poll_timeouts() {
|
||||
Ok(events) => events.iter().for_each(print_event),
|
||||
Err(err) => {
|
||||
eprintln!("timeout polling failed: {err}");
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
match client.close() {
|
||||
Ok(events) => events.iter().for_each(print_event),
|
||||
Err(err) => eprintln!("close failed: {err}"),
|
||||
}
|
||||
}
|
||||
|
||||
fn print_event(event: &ClientEvent) {
|
||||
match event {
|
||||
ClientEvent::EchoReply { seq, rtt, .. } => {
|
||||
println!("seq {seq}: rtt {:?}", rtt.effective);
|
||||
}
|
||||
ClientEvent::EchoLoss { seq, .. } => println!("seq {seq}: lost"),
|
||||
other => println!("{other:?}"),
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
//! Managed multi-target client example (`tokio` feature).
|
||||
//!
|
||||
//! [`BlockingManagedClient`] runs one or more targets under a dedicated
|
||||
//! current-thread Tokio runtime and exposes a synchronous handle, so a caller
|
||||
//! that does not want to touch Tokio directly can still get managed
|
||||
//! multi-target orchestration, retries, and a lossy event stream.
|
||||
//!
|
||||
//! Run a server first, then run this example:
|
||||
//!
|
||||
//! ```text
|
||||
//! cargo run -p irtt-rs --bin irtt-server --features server
|
||||
//! cargo run -p irtt-client --example managed_client --features tokio
|
||||
//! ```
|
||||
//!
|
||||
//! This example does not wait for the managed run to finish naturally: it
|
||||
//! requests a stop after a fixed short window so it exits promptly even
|
||||
//! without a reachable server.
|
||||
|
||||
use std::time::Duration;
|
||||
|
||||
use irtt_client::managed::{
|
||||
BlockingManagedClient, ManagedClientConfig, ManagedCompletionPolicy, ManagedEvent,
|
||||
ManagedTargetConfig,
|
||||
};
|
||||
use irtt_client::ClientConfig;
|
||||
|
||||
fn main() {
|
||||
let config = ManagedClientConfig {
|
||||
client: ClientConfig {
|
||||
duration: None,
|
||||
interval: Duration::from_millis(200),
|
||||
open_timeouts: vec![Duration::from_millis(300)],
|
||||
..Default::default()
|
||||
},
|
||||
completion: ManagedCompletionPolicy::ExplicitStop,
|
||||
..Default::default()
|
||||
};
|
||||
let targets = vec![ManagedTargetConfig::new("local", "127.0.0.1:2112")];
|
||||
|
||||
let (owner, mut events) = match BlockingManagedClient::start_with_subscription(config, targets)
|
||||
{
|
||||
Ok(started) => started,
|
||||
Err(err) => {
|
||||
eprintln!("failed to start managed client: {err}");
|
||||
return;
|
||||
}
|
||||
};
|
||||
|
||||
let stop_after = Duration::from_secs(1);
|
||||
let deadline = std::time::Instant::now() + stop_after;
|
||||
while std::time::Instant::now() < deadline {
|
||||
match events.try_recv() {
|
||||
Ok(event) => print_event(&event),
|
||||
Err(_) => std::thread::sleep(Duration::from_millis(50)),
|
||||
}
|
||||
}
|
||||
|
||||
// `stop()` requests the stop synchronously; the returned receipt is only
|
||||
// useful for awaiting durable acknowledgement, which this blocking
|
||||
// example does not need.
|
||||
std::mem::drop(owner.handle().stop());
|
||||
match owner.join() {
|
||||
Ok(outcome) => println!("managed run ended: {:?}", outcome.end_reason),
|
||||
Err(err) => eprintln!("managed worker did not join cleanly: {err}"),
|
||||
}
|
||||
}
|
||||
|
||||
fn print_event(event: &ManagedEvent) {
|
||||
match event {
|
||||
ManagedEvent::Client { target, event } => println!("{}: {event:?}", target.id),
|
||||
other => println!("{other:?}"),
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,133 @@
|
||||
//! Low-level Tokio client example (`tokio` feature).
|
||||
//!
|
||||
//! Drives [`AsyncClient`] directly on a caller-owned runtime. This is the
|
||||
//! adapter to reach for when you already have a Tokio runtime and want to
|
||||
//! await sends/receives yourself, rather than use the higher-level `managed`
|
||||
//! driver (see the `managed_client` example).
|
||||
//!
|
||||
//! Run a server first, then run this example:
|
||||
//!
|
||||
//! ```text
|
||||
//! cargo run -p irtt-rs --bin irtt-server --features server
|
||||
//! cargo run -p irtt-client --example tokio_client --features tokio
|
||||
//! ```
|
||||
//!
|
||||
//! Without a reachable server this exits quickly with an open-timeout error
|
||||
//! instead of hanging, because the example shortens `open_timeouts` for a
|
||||
//! fast demonstration.
|
||||
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use irtt_client::{AsyncClient, ClientConfig, ClientEvent};
|
||||
|
||||
/// Upper bound on how long the receive wait can go without also calling
|
||||
/// `poll_timeouts()`. `AsyncClient` does not expose the earliest pending
|
||||
/// probe's own timeout deadline, so this example polls on a short fixed
|
||||
/// cadence instead of waiting for the full `probe_timeout()` from whenever
|
||||
/// this loop last ran — that would let poll_timeouts() classify a lost
|
||||
/// probe (and its dependent statistics/session state) far later than it
|
||||
/// actually became lost.
|
||||
const TIMEOUT_POLL_INTERVAL: Duration = Duration::from_millis(50);
|
||||
|
||||
fn main() {
|
||||
let runtime = tokio::runtime::Builder::new_current_thread()
|
||||
.enable_io()
|
||||
.enable_time()
|
||||
.build()
|
||||
.expect("failed to build Tokio runtime");
|
||||
|
||||
runtime.block_on(run());
|
||||
}
|
||||
|
||||
async fn run() {
|
||||
let config = ClientConfig {
|
||||
server_addr: "127.0.0.1:2112".to_owned(),
|
||||
duration: Some(Duration::from_secs(2)),
|
||||
interval: Duration::from_millis(200),
|
||||
// A single short attempt keeps this example fast when no server is
|
||||
// reachable; production callers should generally keep the default.
|
||||
open_timeouts: vec![Duration::from_millis(300)],
|
||||
..Default::default()
|
||||
};
|
||||
|
||||
let mut client = match AsyncClient::connect(config).await {
|
||||
Ok(client) => client,
|
||||
Err(err) => {
|
||||
eprintln!("failed to prepare client socket: {err}");
|
||||
return;
|
||||
}
|
||||
};
|
||||
|
||||
match client.open().await {
|
||||
Ok(outcome) => println!("session opened: {outcome:?}"),
|
||||
Err(err) => {
|
||||
eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
while !client.is_run_complete() {
|
||||
// Bound the receive wait by the next send/timeout deadline, rather
|
||||
// than awaiting recv() unconditionally: a lost or rate-limited reply
|
||||
// must not stall pacing or timeout classification indefinitely.
|
||||
let wake_at = client
|
||||
.next_send_deadline()
|
||||
.into_iter()
|
||||
.chain(std::iter::once(Instant::now() + TIMEOUT_POLL_INTERVAL))
|
||||
.min()
|
||||
.expect("the fixed poll-interval deadline is always present");
|
||||
|
||||
let recv_result = tokio::select! {
|
||||
events = client.recv() => Some(events),
|
||||
() = tokio::time::sleep_until(tokio::time::Instant::from_std(wake_at)) => None,
|
||||
};
|
||||
if let Some(result) = recv_result {
|
||||
match result {
|
||||
Ok(events) => events.iter().for_each(print_event),
|
||||
Err(err) => {
|
||||
eprintln!("receive failed: {err}");
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if client
|
||||
.next_send_deadline()
|
||||
.is_some_and(|send_at| Instant::now() >= send_at)
|
||||
{
|
||||
// A failed send retains its prepared probe without advancing the
|
||||
// schedule, so a persistent error (e.g. the interface going
|
||||
// down) would otherwise make this loop retry forever instead of
|
||||
// reporting it.
|
||||
match client.send_probe().await {
|
||||
Ok(events) => events.iter().for_each(print_event),
|
||||
Err(err) => {
|
||||
eprintln!("send failed: {err}");
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
match client.poll_timeouts() {
|
||||
Ok(events) => events.iter().for_each(print_event),
|
||||
Err(err) => {
|
||||
eprintln!("timeout polling failed: {err}");
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
match client.close().await {
|
||||
Ok(events) => events.iter().for_each(print_event),
|
||||
Err(err) => eprintln!("close failed: {err}"),
|
||||
}
|
||||
}
|
||||
|
||||
fn print_event(event: &ClientEvent) {
|
||||
match event {
|
||||
ClientEvent::EchoReply { seq, rtt, .. } => {
|
||||
println!("seq {seq}: rtt {:?}", rtt.effective);
|
||||
}
|
||||
ClientEvent::EchoLoss { seq, .. } => println!("seq {seq}: lost"),
|
||||
other => println!("{other:?}"),
|
||||
}
|
||||
}
|
||||
@@ -13,10 +13,19 @@
|
||||
//! 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. With the
|
||||
//! `tokio` feature, `AsyncClient` provides the corresponding Tokio adapter;
|
||||
//! [`managed`] contains the unified managed task/handle implementation,
|
||||
//! including the dedicated-runtime blocking frontend for synchronous callers.
|
||||
//! [`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)]
|
||||
|
||||
|
||||
Reference in new issue
Block a user