Struct Timeout

Source

pub struct Timeout { /* private fields */ }

Expand description

A reusable timeout budget that is not yet pinned to a timeline.

A Timeout is just a length (in your chosen monotonic unit). Configure it once and call start per operation to get a Deadline.

Implementations§

Source §

impl Timeout

Source

pub const fn new(budget: u64) -> Self

Creates a timeout with the given budget (its length).

Examples found in repository ?

examples/basic.rs (line 11)

9fn main() {
10    // A 1-second budget for the whole operation.
11    let policy = Timeout::new(1_000);
12
13    // Pretend the operation starts at t = 0.
14    let deadline: Deadline = policy.start(0);
15    println!(
16        "budget: {} ms, expires at t = {}",
17        policy.budget(),
18        deadline.expiry()
19    );
20
21    // A fake monotonic clock and a fixed retry delay.
22    let mut now = 0;
23    let attempt_cost = 250; // each attempt + wait advances the clock by this much
24
25    for attempt in 1.. {
26        match deadline.check(now) {
27            None => {
28                println!(
29                    "t = {now}: deadline expired, giving up after {} attempts",
30                    attempt - 1
31                );
32                break;
33            }
34            Some(remaining) => {
35                // Never wait longer than the time left in the budget.
36                let wait = deadline.clamp(now, attempt_cost);
37                println!("t = {now}: attempt {attempt} ({remaining} ms left, waiting {wait} ms)");
38                now += attempt_cost;
39            }
40        }
41    }
42}

Source

pub const fn budget(&self) -> u64

The budget (length) of this timeout.

Examples found in repository ?

examples/basic.rs (line 17)

9fn main() {
10    // A 1-second budget for the whole operation.
11    let policy = Timeout::new(1_000);
12
13    // Pretend the operation starts at t = 0.
14    let deadline: Deadline = policy.start(0);
15    println!(
16        "budget: {} ms, expires at t = {}",
17        policy.budget(),
18        deadline.expiry()
19    );
20
21    // A fake monotonic clock and a fixed retry delay.
22    let mut now = 0;
23    let attempt_cost = 250; // each attempt + wait advances the clock by this much
24
25    for attempt in 1.. {
26        match deadline.check(now) {
27            None => {
28                println!(
29                    "t = {now}: deadline expired, giving up after {} attempts",
30                    attempt - 1
31                );
32                break;
33            }
34            Some(remaining) => {
35                // Never wait longer than the time left in the budget.
36                let wait = deadline.clamp(now, attempt_cost);
37                println!("t = {now}: attempt {attempt} ({remaining} ms left, waiting {wait} ms)");
38                now += attempt_cost;
39            }
40        }
41    }
42}

Source

pub const fn start(&self, now: u64) -> Deadline

Pins this timeout to the timeline, starting at now.

Examples found in repository ?

examples/basic.rs (line 14)

9fn main() {
10    // A 1-second budget for the whole operation.
11    let policy = Timeout::new(1_000);
12
13    // Pretend the operation starts at t = 0.
14    let deadline: Deadline = policy.start(0);
15    println!(
16        "budget: {} ms, expires at t = {}",
17        policy.budget(),
18        deadline.expiry()
19    );
20
21    // A fake monotonic clock and a fixed retry delay.
22    let mut now = 0;
23    let attempt_cost = 250; // each attempt + wait advances the clock by this much
24
25    for attempt in 1.. {
26        match deadline.check(now) {
27            None => {
28                println!(
29                    "t = {now}: deadline expired, giving up after {} attempts",
30                    attempt - 1
31                );
32                break;
33            }
34            Some(remaining) => {
35                // Never wait longer than the time left in the budget.
36                let wait = deadline.clamp(now, attempt_cost);
37                println!("t = {now}: attempt {attempt} ({remaining} ms left, waiting {wait} ms)");
38                now += attempt_cost;
39            }
40        }
41    }
42}

Source §

impl Timeout

Convenience methods that read the current time from a Clock instead of taking an explicit now: u64.

Available with the core feature. Each forwards to the matching now-taking method, which remains the primitive API.

Source

pub fn start_now<C: Clock>(&self, clock: &C) -> Deadline

Like start, reading the start instant from clock.

use reliakit_timeout::Timeout;
use reliakit_core::ManualClock;

let clock = ManualClock::new(1_000);
let deadline = Timeout::new(30_000).start_now(&clock);
clock.advance(10_000);
assert_eq!(deadline.remaining_now(&clock), 20_000);
assert!(!deadline.is_expired_now(&clock));