Struct IperfCommand 

pub struct IperfCommand { /* private fields */ }

Builder for running an iperf test through libiperf.

The typed helpers append ordinary iperf arguments such as -c, -p, and -t. The lower-level IperfCommand::arg and IperfCommand::args methods remain available for upstream options that do not have a dedicated Rust helper.

Library runs suppress libiperf’s normal stdout output by default. Use IperfCommand::inherit_output for upstream-style terminal output or IperfCommand::logfile to send that output to a file.

Execution model

High-level runs are serialized inside the process because libiperf keeps process-global state. RunningIperf is therefore a completion observer, not a cancellation handle. Dropping it detaches the worker thread, and RunningIperf::wait_timeout only stops waiting. It does not stop libiperf or release this crate’s process-wide run lock.

Use one-off server mode for library servers, or run long-lived and externally cancellable iperf workloads in a helper process that the embedding application can terminate.

Examples

use std::time::Duration;

use iperf3_rs::{IperfCommand, Result};

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

    let result = command.run()?;
    println!("{:?}", result.role());
    Ok(())
}

Implementations

impl IperfCommand

pub fn new() -> Self

Create a command with no iperf role selected yet.

pub fn client(host: impl Into<String>) -> Self

Create a client command equivalent to iperf3 -c HOST.

pub fn server_once() -> Self

Create a one-off server command equivalent to iperf3 -s -1.

This is the preferred server constructor for library code because the run exits after one accepted test and releases the process-wide libiperf lock.

pub fn server_unbounded() -> Self

Create a long-lived server command equivalent to iperf3 -s.

Long-lived servers keep the high-level libiperf lock held until the server exits. The library does not provide in-process cancellation for an active libiperf server, and dropping RunningIperf detaches rather than stops it. Use this only for a process dedicated to serving tests or for a helper process that the parent application can terminate from the outside.

pub fn program(&mut self, program: impl Into<String>) -> &mut Self

Override the program name passed as argv[0] to libiperf.

pub fn arg(&mut self, arg: impl Into<String>) -> &mut Self

Append one iperf argument.

pub fn args<I, S>(&mut self, args: I) -> &mut Self

where I: IntoIterator<Item = S>, S: Into<String>,

Append several iperf arguments.

pub fn port(&mut self, port: u16) -> &mut Self

Set the server port with iperf’s -p option.

pub fn duration(&mut self, duration: Duration) -> &mut Self

Set client test duration with iperf’s -t option.

Upstream iperf parses -t as whole seconds. Sub-second durations are rounded up so the typed API does not silently truncate a nonzero Duration to 0.

pub fn report_interval(&mut self, interval: Duration) -> &mut Self

Set reporting interval with iperf’s -i option.

pub fn logfile(&mut self, path: impl AsRef<Path>) -> &mut Self

Send iperf output to a log file with iperf’s --logfile option.

Explicit log files are honored even though high-level library runs are quiet by default.

pub fn quiet(&mut self) -> &mut Self

Suppress libiperf’s normal text or JSON writes to the process stdout.

This is the default for IperfCommand so library use does not unexpectedly write to the embedding application’s terminal. Retained JSON remains available through IperfResult::json_output when IperfCommand::json is enabled.

pub fn inherit_output(&mut self) -> &mut Self

Let libiperf write normal output to this process’ stdout.

This matches upstream iperf3 output behavior for applications that intentionally want human-readable output from library runs.

pub fn connect_timeout(&mut self, timeout: Duration) -> &mut Self

Set control connection setup timeout with iperf’s --connect-timeout.

Upstream iperf expects milliseconds. Nonzero sub-millisecond durations are rounded up so intent is not lost.

pub fn omit(&mut self, duration: Duration) -> &mut Self

Omit pre-test statistics for the given duration with iperf’s -O.

pub fn bind(&mut self, address: impl Into<String>) -> &mut Self

Bind to a local address or address%device with iperf’s -B.

pub fn udp(&mut self) -> &mut Self

Enable UDP mode with iperf’s -u option.

pub fn sctp(&mut self) -> &mut Self

Enable SCTP mode with iperf’s --sctp option.

This option is available only when the linked libiperf was built with SCTP support; otherwise libiperf reports the unsupported option.

pub fn bitrate_bits_per_second(&mut self, bits_per_second: u64) -> &mut Self

Set target bitrate in bits per second with iperf’s -b option.

pub fn parallel_streams(&mut self, streams: u16) -> &mut Self

Set the number of parallel client streams with iperf’s -P option.

pub fn reverse(&mut self) -> &mut Self

Enable reverse mode with iperf’s -R option.

pub fn bidirectional(&mut self) -> &mut Self

Enable bidirectional mode with iperf’s --bidir option.

pub fn no_delay(&mut self) -> &mut Self

Disable Nagle’s algorithm with iperf’s -N option.

pub fn zerocopy(&mut self) -> &mut Self

Use zero-copy send with iperf’s -Z option.

pub fn congestion_control(&mut self, algorithm: impl Into<String>) -> &mut Self

Set TCP congestion control algorithm with iperf’s -C option.

Upstream support depends on the operating system and linked libiperf build; unsupported values are reported by libiperf when the command parses or runs.

pub fn json(&mut self) -> &mut Self

Request retained JSON output with iperf’s -J option.

pub fn metrics(&mut self, mode: MetricsMode) -> &mut Self

Enable or disable callback metrics for this run.

MetricsMode::Interval and MetricsMode::Window preserve every emitted event. Callers that spawn a metrics stream must keep draining it for the lifetime of the run. Blocking IperfCommand::run collects all emitted events in memory before returning, so it is intended for bounded client runs or one-off servers rather than long-lived servers.

pub fn pushgateway( &mut self, config: PushGatewayConfig, mode: MetricsMode, ) -> &mut Self

Push live metrics for this run directly to a Pushgateway.

MetricsMode::Interval uses the same freshness-oriented queue as the CLI’s immediate push mode. MetricsMode::Window(duration) uses the same aggregation behavior as --push.interval. MetricsMode::Disabled is rejected when the command is started.

Direct Pushgateway delivery and IperfCommand::spawn_with_metrics are currently mutually exclusive for one run because libiperf exposes a single reporter callback. Use IperfCommand::spawn_with_metrics plus PushGateway::push or PushGateway::push_window when application code needs both live inspection and custom push behavior.

Delivery is best-effort: Pushgateway push/delete failures are logged to stderr and do not make the iperf run fail. Applications that require strict delivery should use IperfCommand::spawn_with_metrics and call PushGateway::push or PushGateway::push_window themselves.

pub fn clear_pushgateway(&mut self) -> &mut Self

Disable direct Pushgateway delivery for this command.

pub fn run_with_pushgateway( &self, config: PushGatewayConfig, mode: MetricsMode, ) -> Result<IperfResult>

Run the iperf test to completion while pushing metrics to Pushgateway.

Pushgateway delivery uses the same best-effort policy as the CLI. This method returns an error for setup or libiperf execution failures, but transient push/delete failures are logged and do not change the result. Use IperfCommand::spawn_with_metrics plus PushGateway::push or PushGateway::push_window when delivery failures must be handled strictly by application code.

pub fn spawn_with_pushgateway( &self, config: PushGatewayConfig, mode: MetricsMode, ) -> Result<RunningIperf>

Run iperf on a worker thread while pushing metrics to Pushgateway.

Pushgateway delivery is best-effort for this convenience method; use IperfCommand::spawn_with_metrics and call PushGateway directly when the application must treat delivery errors as run failures.

pub fn allow_unbounded_server(&mut self, allow: bool) -> &mut Self

Allow -s server runs that do not include iperf’s one-off option.

Long-lived servers keep libiperf running on the worker thread and keep this crate’s process-wide libiperf lock held. The default is therefore conservative: server mode must use -1/--one-off unless this opt-in is set. The CLI does not use this high-level API, so normal iperf3-rs -s behavior is unchanged. Once started, an unbounded in-process server must exit through libiperf itself; this API intentionally does not expose an in-process cancellation primitive. Prefer a dedicated helper process whenever the owner must enforce an external timeout or stop policy.

pub fn run(&self) -> Result<IperfResult>

Run the iperf test to completion and collect metric events in memory.

When metrics are enabled, every emitted event is retained in the returned IperfResult. Keep metrics disabled for long-running or unbounded runs, or use IperfCommand::spawn_with_metrics and drain the stream while the run is active.

pub fn spawn(&self) -> Result<RunningIperf>

Run iperf on a worker thread and optionally stream metric events live.

If metrics are enabled, call RunningIperf::take_metrics before RunningIperf::wait to consume live events. Dropping the returned handle detaches the worker and does not cancel the underlying libiperf run. If you keep the metrics stream, drain it continuously for the lifetime of the run; every-sample streams use unbounded queues so the libiperf reporting callback never blocks on application code.

pub fn spawn_with_metrics( &self, mode: MetricsMode, ) -> Result<(RunningIperf, MetricsStream)>

Run iperf on a worker thread and return the live metric stream.

This is a convenience wrapper around IperfCommand::metrics, IperfCommand::spawn, and RunningIperf::take_metrics for callers that know they want metrics for this run. The returned stream is part of the run contract: drain it until it closes, or drop it if metrics are no longer needed. Keeping it alive but unread can grow memory on long runs.

Trait Implementations

impl Clone for IperfCommand

fn clone(&self) -> IperfCommand

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IperfCommand

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

Formats the value using the given formatter.

impl Default for IperfCommand

fn default() -> Self

Returns the “default value” for a type.