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}