Struct RoundTripLatencySession 

pub struct RoundTripLatencySession;

Self-contained round-trip latency measurement session.

RoundTripLatencySession has no fields; it acts as a namespace for the run function. All state lives on the stack inside that call, making the session automatically torn down when it returns — there is nothing to clean up manually.

Thread safety

run is a blocking call designed to execute on a dedicated thread. The caller (measure_round_trip_latency Tauri command) clones the handler reference, releases the Mutex<AudioService> lock, and then spawns a thread that calls this function. This means the main audio engine remains fully operational during the measurement.

Implementations

impl RoundTripLatencySession

pub fn run( handler: &dyn AudioHandlerTrait, per_impulse_timeout: Duration, stream_warmup: Duration, ) -> Result<f64, String>

Runs a complete round-trip latency measurement and returns the average in milliseconds.

What this function does

1. Determines a safe ring-buffer size from the handler’s configured buffer frames (falling back to 256 if BufferSize::Default is in use), then multiplies by 4 to give the streams room to breathe during warmup and calibration.
2. Creates a dedicated input ring buffer (i_producer → i_consumer) and a dedicated output ring buffer (o_producer → o_consumer), both completely separate from the main loopback ring buffers.
3. Opens a CPAL input stream that pushes captured samples into i_producer and a CPAL output stream that drains processed samples from o_consumer, then starts both.
4. Sleeps for stream_warmup to let the OS audio scheduler and hardware settle.
5. Drains all samples accumulated during warmup from i_consumer so that calibration begins with fresh, stable ambient data.
6. Enters the main sample-processing loop, feeding each incoming sample to RoundTripMeasurementState::tick until a terminal outcome is reached or the overall_deadline expires.

The overall_deadline is set to per_impulse_timeout × IMPULSE_COUNT + 2 s to account for calibration time and inter-impulse gaps while still guaranteeing the function cannot block indefinitely.

Arguments

• handler — Audio I/O factory. Used only to size ring buffers and build streams; it is not the same handler instance that the main loopback uses concurrently.
• per_impulse_timeout — Maximum time to wait for a single echo after the impulse is emitted. Recommended: 10 s for real hardware, shorter for unit tests.
• stream_warmup — How long to sleep after starting streams before beginning calibration. Recommended: 1–2 s to allow ASIO/WASAPI buffers to stabilise.

Returns

• Ok(latency_ms) — Averaged round-trip latency across all IMPULSE_COUNT cycles.
• Err(message) — Human-readable failure reason; either a timeout, an undetectable echo (signal too quiet or output not routed to input), or an overall deadline breach.