vector_core/time.rs
1//! Time utilities for vector-core
2
3use std::task::{Context, Poll};
4
5/// A trait for representing a timer which holds multiple subtimers, mapped by an arbitrary key, `K`.
6///
7/// Embedding time as a type into other types eases property testing and verification. As such,
8/// this trait represents the minimum functionality required to describe management of keyed timers
9/// for the types implemented in this crate that require such behavior.
10///
11/// Users can look at `vector_stream::batcher::ExpirationQueue` for a concrete implementation.
12pub trait KeyedTimer<K> {
13 /// Clear the timer.
14 ///
15 /// Clears all keys from the timer. Future calls to `poll_expired` will return `None` until
16 /// another key is added.
17 fn clear(&mut self);
18
19 /// Insert a new subtimer, keyed by `K`.
20 ///
21 /// If the given key already exists in the timer, the underlying subtimer is reset.
22 fn insert(&mut self, item_key: K);
23
24 /// Removes a subtimer from the list.
25 fn remove(&mut self, item_key: &K);
26
27 /// Attempts to pull out the next expired subtimer in the queue.
28 ///
29 /// The key of the subtimer is returned if it has expired, otherwise, returns `None` if the
30 /// the queue is exhausted.
31 ///
32 /// Unlike a typical stream, returning `None` only indicates that the queue
33 /// is empty, not that the queue will never return anything else in the future.
34 ///
35 /// Used primarily for property testing vis-รก-vis `vector_stream::batcher::Batcher`.
36 fn poll_expired(&mut self, cx: &mut Context) -> Poll<Option<K>>;
37}