Struct DebouncedTimeout 

pub struct DebouncedTimeout<T> { /* private fields */ }

A Stop wrapper that debounces the Instant::now() call.

After a brief calibration phase, check() only reads the clock every N calls, where N is chosen so clock reads happen approximately once per target_interval.

Adaptation behavior:

• If calls slow down (longer between checks), immediately increases check frequency to avoid missing the deadline.
• If calls speed up (shorter between checks), gradually decreases check frequency to avoid over-checking.

When to Use

Prefer DebouncedTimeout over WithTimeout when the Stop implementation crosses an API boundary — the caller adds the deadline, but the library controls check frequency. This avoids coupling timeout overhead to the library’s internal loop structure.

In tight loops (sub-microsecond between checks), the savings are ~10x. In codec workloads (~4KB between checks), both types are equivalent because the real work dwarfs the clock read.

Example

use almost_enough::{StopSource, Stop};
use almost_enough::time::DebouncedTimeout;
use std::time::Duration;

let source = StopSource::new();
let stop = DebouncedTimeout::new(source.as_ref(), Duration::from_millis(100));

// Fast loop — most check() calls skip the clock read
let mut i = 0u64;
while !stop.should_stop() {
    i += 1;
    if i > 1_000_000 { break; }
}

Implementations

impl<T: Stop> DebouncedTimeout<T>

pub fn new(inner: T, duration: Duration) -> Self

Create a new debounced timeout with the default target interval (100μs).

The deadline is calculated as Instant::now() + duration. Durations longer than ~584 years are clamped to u64::MAX nanoseconds.

pub fn with_deadline(inner: T, deadline: Instant) -> Self

Create a debounced timeout with an absolute deadline.

If the deadline is in the past, the first clock read will trigger StopReason::TimedOut.

pub fn with_target_interval(self, interval: Duration) -> Self

Set the target interval between clock reads.

Smaller values check the clock more often (more responsive but more overhead). Larger values check less often (less overhead but may overshoot the deadline by up to this amount).

Default: 100μs (0.1ms).

pub fn deadline(&self) -> Instant

Get the deadline as an Instant.

pub fn remaining(&self) -> Duration

Get the remaining time until deadline.

Returns Duration::ZERO if the deadline has passed.

pub fn inner(&self) -> &T

Get a reference to the inner stop.

pub fn into_inner(self) -> T

Unwrap and return the inner stop.

pub fn checks_per_clock_read(&self) -> u32

Current number of check() calls between clock reads.

Starts at 1 (every call) and adapts upward as the call rate is measured. Useful for diagnostics and testing.

impl<T: Stop> DebouncedTimeout<T>

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

Add another timeout, taking the tighter of the two deadlines.

Resets calibration state since the new deadline may require a different check frequency.

pub fn tighten_deadline(self, deadline: Instant) -> Self

Add another deadline, taking the earlier of the two.

Resets calibration state since the new deadline may require a different check frequency.

Trait Implementations

impl<T: Clone + Stop> Clone for DebouncedTimeout<T>

fn clone(&self) -> Self

Clone resets calibration state — each clone starts fresh.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for DebouncedTimeout<T>

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

Formats the value using the given formatter.

impl<T: Stop> Stop for DebouncedTimeout<T>

fn check(&self) -> Result<(), StopReason>

Check if the operation should stop.

fn should_stop(&self) -> bool

Returns true if the operation should stop.

fn may_stop(&self) -> bool

Returns true if this stop can ever signal a stop.