pub struct TimeoutQueue<T: 'static, S: SlabStore<Item = WheelEntry<T>> = Slab<WheelEntry<T>>> { /* private fields */ }Expand description
A fixed-duration timeout queue with O(fired) poll and O(1) exact next-deadline.
Generic over:
T— the user payload stored with each timer.S— the slab storage backend. Defaults tounbounded::Slab.
Every timer uses the same duration, fixed at construction. See the module docs for the invariant this exploits.
§No reschedule
Rescheduling later is push-to-tail and stays ordered, but rescheduling
earlier would break the sort — and the two are indistinguishable in a
single API. So no reschedule is offered: callers cancel and re-schedule,
which is the same two operations without the ordering hazard. (This mirrors
the wheel’s reschedule, deliberately omitted here.)
§Thread Safety
Send but !Sync. Can be moved to a thread at setup but must not be
shared. All internal raw pointers point into owned allocations (slab
chunks) — moving the list moves the heap data with it.
Implementations§
Source§impl<T: 'static> TimeoutQueue<T>
impl<T: 'static> TimeoutQueue<T>
Sourcepub fn unbounded(timeout: Duration, chunk_capacity: usize, now: Instant) -> Self
pub fn unbounded(timeout: Duration, chunk_capacity: usize, now: Instant) -> Self
Creates an unbounded timeout queue with the default 1ms tick.
Every timer fires timeout after the now passed to schedule. The
now here fixes the reference epoch — pass one monotone clock source
(e.g. Instant::now()) here and to every schedule/poll. For a custom
tick duration, use TimeoutQueueBuilder.
§Panics
Panics if timeout is zero. Use [TimeoutQueueBuilder::build] to handle
a runtime-sourced timeout without panicking.
Source§impl<T: 'static> TimeoutQueue<T, Slab<WheelEntry<T>>>
impl<T: 'static> TimeoutQueue<T, Slab<WheelEntry<T>>>
Sourcepub fn bounded(timeout: Duration, capacity: usize, now: Instant) -> Self
pub fn bounded(timeout: Duration, capacity: usize, now: Instant) -> Self
Creates a bounded timeout queue with the default 1ms tick.
Every timer fires timeout after the now passed to schedule. The
now here fixes the reference epoch — pass one monotone clock source
(e.g. Instant::now()) here and to every schedule/poll. For a custom
tick duration, use TimeoutQueueBuilder.
§Panics
Panics if timeout is zero. Use [TimeoutQueueBuilder::build] to handle
a runtime-sourced timeout without panicking.
Source§impl<T: 'static, S: SlabStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>
impl<T: 'static, S: SlabStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>
Sourcepub fn schedule(&mut self, now: Instant, value: T) -> TimerHandle<T>
pub fn schedule(&mut self, now: Instant, value: T) -> TimerHandle<T>
Schedules a timer for now + timeout and returns a handle for cancellation.
The handle must be consumed via cancel or
free. Dropping it is a programming error.
now must be monotonically non-decreasing across calls (a plain
Instant::now() at each call site satisfies this). A now that goes
backwards trips a debug_assert! in debug builds.
§Panics
Panics if the backing slab is at capacity (bounded slabs only). This is a capacity planning error — size the list for peak load.
Sourcepub fn schedule_forget(&mut self, now: Instant, value: T)
pub fn schedule_forget(&mut self, now: Instant, value: T)
Source§impl<T: 'static, S: BoundedStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>
impl<T: 'static, S: BoundedStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>
Sourcepub fn try_schedule(
&mut self,
now: Instant,
value: T,
) -> Result<TimerHandle<T>, Full<T>>
pub fn try_schedule( &mut self, now: Instant, value: T, ) -> Result<TimerHandle<T>, Full<T>>
Attempts to schedule a timer, returning a handle on success.
Returns Err(Full(value)) — with the caller’s T recovered, not the
internal WheelEntry — if the slab is at capacity. Use this when
capacity exhaustion should be handled gracefully; otherwise use
schedule.
Sourcepub fn try_schedule_forget(
&mut self,
now: Instant,
value: T,
) -> Result<(), Full<T>>
pub fn try_schedule_forget( &mut self, now: Instant, value: T, ) -> Result<(), Full<T>>
Attempts to schedule a fire-and-forget timer.
Returns Err(Full(value)) — with the caller’s T recovered — if the
slab is at capacity. Otherwise use schedule_forget.
Source§impl<T: 'static, S: SlabStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>
impl<T: 'static, S: SlabStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>
Sourcepub fn cancel(&mut self, handle: TimerHandle<T>) -> Option<T>
pub fn cancel(&mut self, handle: TimerHandle<T>) -> Option<T>
Cancels a timer and returns its value.
- Still active (refs == 2): unlinks from the list, extracts the value,
frees the slab entry. Returns
Some(T). O(1) — a mid-list unlink, no residency, no tombstone. - Already fired (zombie handle, refs == 1): frees the slab entry.
Returns
None.
Consumes the handle (no Drop runs).
Sourcepub fn free(&mut self, handle: TimerHandle<T>)
pub fn free(&mut self, handle: TimerHandle<T>)
Releases a timer handle without cancelling.
- Still active: converts to fire-and-forget (refs 2 -> 1). The timer stays in the list and fires normally during poll.
- Already fired (zombie): frees the slab entry (refs 1 -> 0).
Consumes the handle (no Drop runs).
Sourcepub fn poll(&mut self, now: Instant, buf: &mut Vec<T>) -> usize
pub fn poll(&mut self, now: Instant, buf: &mut Vec<T>) -> usize
Fires all expired timers, collecting their values into buf.
Returns the number of timers fired. O(fired): the list is sorted, so this walks from the head and stops at the first not-due entry.
Sourcepub fn poll_with_limit(
&mut self,
now: Instant,
limit: usize,
buf: &mut Vec<T>,
) -> usize
pub fn poll_with_limit( &mut self, now: Instant, limit: usize, buf: &mut Vec<T>, ) -> usize
Fires expired timers up to limit, collecting values into buf.
Returns the number fired in this call. Truncation is resumable: this
stops at a head that is either not-due or beyond limit, and the next
call picks up at exactly that head. No bookmark is needed — the sorted
list is the cursor. (The wheel needs a resumption argument because it
re-derives its scan position each call; here there is nothing to
re-derive.)
Sourcepub fn next_deadline(&self) -> Option<Instant>
pub fn next_deadline(&self) -> Option<Instant>
Returns the Instant of the next timer that will fire, or None if empty.
O(1), exact: the sorted list’s head is the minimum deadline. No cache.