Struct Client 

pub struct Client { /* private fields */ }

Low-level synchronous IRTT client.

Client exposes the protocol steps directly: connect a UDP socket, open a session, send probes, receive replies, poll timeouts, and close. Callers that do not need to own this loop can use the unified managed API in crate::managed when the tokio feature is enabled.

Example

Client is the runtime-free adapter. The caller drives receives and timeout polling between sends; see the standalone example for a complete loop. This example type-checks without contacting a server:

use irtt_client::{Client, ClientConfig};

let mut client = Client::connect("127.0.0.1:2112", ClientConfig::default())?;
let outcome = client.open()?;
println!("opened: {outcome:?}");
let sent = client.send_probe()?;
println!("sent: {sent:?}");
let received = client.recv_once()?;
println!("received: {received:?}");
let timed_out = client.poll_timeouts()?;
println!("timeouts: {timed_out:?}");
let closed = client.close()?;
println!("closed: {closed:?}");

Implementations

impl Client

pub fn connect( endpoint: impl AsRef<str>, config: ClientConfig, ) -> Result<Self, ClientError>

Resolve the endpoint and create a connected UDP socket.

This validates local configuration and prepares the open request, but it does not contact the server. Call open to perform the IRTT open exchange.

The endpoint accepts a name or address; an omitted port defaults to 2112. IPv6 literals may be bracketed or unbracketed with the default port. The reusable config contains no endpoint identity.

Examples found in repository

examples/blocking_client.rs (line 41)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn set_recv_timeout( &mut self, timeout: Option<Duration>, ) -> Result<(), ClientError>

Set the blocking receive timeout used outside open attempts.

None (the default) lets recv_once() block indefinitely. A nonzero timeout bounds one logical receive, including retries after EINTR. recv_available() retains its bounded drain behavior. Open attempts use only OpenPolicy::timeouts and restore this setting on success or failure.

A zero duration is rejected by the socket; the previous setting is retained when applying the new timeout fails.

Examples found in repository

examples/blocking_client.rs (line 49)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn open(&mut self) -> Result<OpenOutcome, ClientError>

Perform the IRTT open exchange.

On success, returns the negotiated open outcome and transitions the client into either an open probe session or completed no-test state. Open attempts use OpenPolicy::timeouts. Malformed or unrelated datagrams are ignored until the current attempt’s absolute deadline, so one attempt may consume several datagrams without retransmitting. Silence or ignored traffic eventually produces ClientError::OpenTimeout. A structurally recognizable malformed or incompatible Open reply from the connected peer is terminal; when HMAC is configured, that recognition additionally requires authentication.

When a trusted reply allocates a token but later negotiation or socket preparation fails, the client sends a best-effort cleanup close and preserves the original failure. Failed opening never leaves the session machine open.

Examples found in repository

examples/blocking_client.rs (line 54)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn close(&mut self) -> Result<Vec<ClientEvent>, ClientError>

Send a close request and emit a ClientEvent::SessionClosed event.

The close event means the client has sent its close packet and stopped tracking the session locally; it is not a server acknowledgement. If the send fails, the negotiated DSCP is restored best-effort and the session remains open.

Examples found in repository

examples/blocking_client.rs (line 120)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn probe_timeout(&self) -> Duration

Return the local timeout used to classify pending probes as lost.

Examples found in repository

examples/blocking_client.rs (line 77)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn send_probe(&mut self) -> Result<SendReceipt, SendProbeError>

Send one echo probe now. The caller owns pacing and run duration.

The negotiated interval and duration do not gate low-level sends. A receipt means socket acceptance and infallible session commitment have completed. Failures before acceptance return SendProbeError::NotCommitted; later validation or TX processing failures preserve the receipt in SendProbeError::AfterCommit.

Examples found in repository

examples/blocking_client.rs (line 85)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn recv_once(&mut self) -> Result<Vec<ClientEvent>, ClientError>

Receive and classify at most one datagram from the socket.

Returns an empty event list when the socket read would block or times out. Malformed or unrelated datagrams are reported as warning events. Requires an open session; lifecycle errors are returned before socket I/O.

Examples found in repository

examples/blocking_client.rs (line 101)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn recv_available( &mut self, budget: RecvBudget, ) -> Result<Vec<ClientEvent>, ClientError>

Receive and classify datagrams until a receive produces no events or the receive budget is exhausted.

Requires an open session; lifecycle errors are returned before socket I/O.

pub fn poll_timeouts(&mut self) -> Result<Vec<ClientEvent>, ClientError>

Polls for probes that have timed out as of the current monotonic time.

Examples found in repository

examples/blocking_client.rs (line 108)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn poll_timeouts_at( &mut self, now: Instant, ) -> Result<Vec<ClientEvent>, ClientError>

Polls for probes that have timed out as of now.

This is useful for callers that drive Client from their own event loop and want timeout decisions to use the same sampled Instant as their scheduling logic.

now is monotonic time only; wall-clock time is not used for timeout expiry.

pub fn negotiation(&self) -> Option<&NegotiationResult>

Accepted semantics and exact peer parameters of the currently live session.

Returns None before Open, after Close, and after no-test completion.

pub fn next_probe_timeout_deadline(&self) -> Option<Instant>

Earliest timeout deadline among probes still awaiting a reply.

pub fn has_pending_probes(&self) -> bool

Whether any sent probes still await a reply or timeout.

Examples found in repository

examples/blocking_client.rs (line 81)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

pub fn is_peer_closed(&self) -> bool

Return whether the session was closed by a peer close-flagged reply.

Direct operations on a closed client still return ClientError::AlreadyClosed. This method lets higher-level run loops avoid treating a successfully observed peer close as a local cleanup failure.

Examples found in repository

examples/blocking_client.rs (line 79)

fn main() {
    let config = ClientConfig {
        open: OpenPolicy {
            // A single short attempt keeps this example fast when no server is
            // reachable; production callers should generally keep the default.
            timeouts: vec![Duration::from_millis(300)],
            ..Default::default()
        },
        request: SessionRequest {
            duration: Some(RUN_DURATION),
            interval: Duration::from_millis(200),
            ..Default::default()
        },
        ..Default::default()
    };

    let mut client = match Client::connect("127.0.0.1:2112", config) {
        Ok(client) => client,
        Err(err) => {
            eprintln!("failed to prepare client socket: {err}");
            return;
        }
    };

    if let Err(err) = client.set_recv_timeout(Some(Duration::from_millis(100))) {
        eprintln!("failed to configure receive timeout: {err}");
        return;
    }

    let negotiated = match client.open() {
        Ok(OpenOutcome::Started(started)) => {
            println!("session opened: {started:?}");
            started.negotiation
        }
        Ok(OpenOutcome::NoTestCompleted(completed)) => {
            println!("{completed:?}");
            return;
        }
        Err(err) => {
            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
            return;
        }
    };

    // This loop owns cadence and duration. The transport sends whenever called.
    let interval = negotiated.accepted.interval;
    let start = Instant::now();
    let end = start
        + negotiated
            .accepted
            .duration
            .expect("example requests a finite run");
    let deadline = end + client.probe_timeout();
    let mut next_send = start;
    while Instant::now() < deadline && !client.is_peer_closed() {
        let now = Instant::now();
        if now >= end && !client.has_pending_probes() {
            break;
        }
        if now < end && now >= next_send {
            match client.send_probe() {
                Ok(receipt) => {
                    print_event(&receipt.into());
                    while next_send <= Instant::now() {
                        next_send += interval;
                    }
                }
                Err(err) => {
                    if let irtt_client::SendProbeError::AfterCommit { receipt, .. } = &err {
                        print_event(&(*receipt).into());
                    }
                    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;
            }
        }
    }

    if client.is_peer_closed() {
        return;
    }
    match client.close() {
        Ok(events) => events.iter().for_each(print_event),
        Err(err) => eprintln!("close failed: {err}"),
    }
}

Trait Implementations

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.