Crate iperf3_rs 

Rust frontend APIs for driving upstream libiperf.

iperf3-rs links upstream esnet/iperf3 through FFI. The high-level IperfCommand API accepts ordinary iperf arguments, lets libiperf parse and run them, and can stream the same live interval metrics used by the CLI’s Pushgateway exporter. Protocol-specific metrics are optional, so callers can distinguish a real zero from values that libiperf did not report for a TCP, UDP, or SCTP run. Metrics callbacks emit one aggregate stream direction per libiperf reporting interval. In bidirectional mode the client-side aggregate is the sending direction and the server-side aggregate is the receiving direction; this crate does not currently emit both bidirectional halves from one process.

This crate is useful when a Rust program needs to run iperf tests directly, for example from a bot, controller, or test harness, without spawning an external iperf3-rs process and parsing stdout. High-level library runs suppress libiperf’s ordinary stdout output by default; use IperfCommand::inherit_output or IperfCommand::logfile when an application intentionally wants upstream text output.

Examples

Run a client and consume live interval metrics:

use std::time::Duration;

use iperf3_rs::{IperfCommand, MetricEvent, MetricsMode, Result};

fn main() -> Result<()> {
    let mut command = IperfCommand::client("127.0.0.1");
    command
        .duration(Duration::from_secs(10))
        .report_interval(Duration::from_secs(1));

    let (running, mut metrics) = command.spawn_with_metrics(MetricsMode::Interval)?;

    while let Some(event) = metrics.recv() {
        match event {
            MetricEvent::Interval(sample) => {
                println!("{} bit/s", sample.bandwidth_bits_per_second);
            }
            MetricEvent::Window(window) => {
                println!("{} bytes", window.transferred_bytes);
            }
            _ => {}
        }
    }

    running.wait()?;
    Ok(())
}

Concurrency

High-level IperfCommand runs are serialized inside the process. libiperf has process-global state for errors, signal handling, and output hooks, so this crate intentionally avoids promising in-process parallelism that upstream does not clearly guarantee. Server runs must use iperf’s one-off mode (-s -1) by default; opt in with IperfCommand::allow_unbounded_server only when the process is dedicated to that long-lived server.

RunningIperf observes worker completion; it is not a cancellation or kill handle. Dropping it detaches the worker, and RunningIperf::wait_timeout only stops waiting. It does not stop libiperf. Use a separate process, container, VM, or another process-backed wrapper for runs that must be externally terminated, isolated from hangs, or executed in parallel.

Metrics stream ownership

MetricsMode::Interval and MetricsMode::Window are every-sample library streams. They preserve all events by using unbounded internal queues, so long-running runs must continuously drain MetricsStream or disable metrics. IperfCommand::run collects emitted events in memory before returning; do not combine it with metrics for unbounded server runs or other runs that can produce an unbounded number of samples.

Structs

Error

Error returned by the public library API.

IperfCommand

Builder for running an iperf test through libiperf.

IperfResult

Completed result from a blocking or spawned iperf run.

Metrics

One libiperf interval sample.

MetricsFileSink

Writer for one metrics output file.

MetricsStream

Receiver for metric events emitted by a running iperf test.

PrometheusEncoder

Encoder for Prometheus text exposition snapshots.

PushGateway

HTTP sink for pushing iperf metrics to Prometheus Pushgateway.

PushGatewayConfig

Configuration for a PushGateway sink.

RunningIperf

Handle for an iperf run executing on a worker thread.

WindowGaugeStats

Mean, minimum, and maximum values for a gauge-like metric in a window.

WindowMetrics

Summary of one aggregated metrics window.

Enums

ErrorKind

Broad category for an Error.

MetricDirection

Direction of the libiperf streams represented by a metrics sample.

MetricEvent

Metric event emitted by a running iperf test.

MetricsFileFormat

File output format for metrics snapshots.

MetricsMode

Controls whether a run emits live metrics and how interval samples are shaped.

MetricsRecvError

Reason a non-blocking or timed metrics receive did not return an event.

Role

Role selected by libiperf after parsing iperf arguments.

TransportProtocol

Transport protocol selected by libiperf for a metrics sample.

Functions

aggregate_window

Aggregate raw interval samples into one representative window.

libiperf_version

Return the upstream libiperf version string.

usage_long

Render the upstream iperf3 long help text.

Type Aliases

Result

Result type used by the public iperf3-rs library API.