nexus-timer 1.4.1

High-performance timer wheel with O(1) insert and cancel
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

//! Timer handle — proof that a timer was scheduled with the intent to cancel.
//!
//! A `TimerHandle<T>` is an 8-byte, move-only token returned by `schedule()`.
//! It must be explicitly consumed via `wheel.cancel(handle)` or
//! `wheel.free(handle)`. Dropping a handle without consuming it is a
//! programming error (caught by `debug_assert!` in debug builds).

use std::fmt;
use std::marker::PhantomData;

use crate::entry::EntryPtr;

/// Handle to a scheduled timer.
///
/// Returned by [`TimerWheel::schedule`](crate::TimerWheel::schedule) and
/// [`TimerWheel::try_schedule`](crate::TimerWheel::try_schedule). Must be
/// consumed by one of:
///
/// - [`TimerWheel::cancel`](crate::TimerWheel::cancel) — unlinks from the
///   wheel and extracts the value.
/// - [`TimerWheel::free`](crate::TimerWheel::free) — releases the handle,
///   converting to fire-and-forget.
///
/// Dropping without consuming is a programming error (`debug_assert!` fires).
///
/// # Size
///
/// 8 bytes (one pointer). `!Send`, `!Sync`, `!Clone`, `!Copy`.
#[must_use = "handles must be consumed via cancel() or free(), dropping leaks the timer slot"]
pub struct TimerHandle<T> {
    pub(crate) ptr: EntryPtr<T>,
    // !Send, !Sync
    _marker: PhantomData<*const ()>,
}

impl<T> TimerHandle<T> {
    /// Creates a new handle from an entry pointer.
    #[inline]
    pub(crate) fn new(ptr: EntryPtr<T>) -> Self {
        TimerHandle {
            ptr,
            _marker: PhantomData,
        }
    }
}

impl<T> Drop for TimerHandle<T> {
    fn drop(&mut self) {
        debug_assert!(
            false,
            "TimerHandle dropped without being consumed — call wheel.cancel() or wheel.free()"
        );
    }
}

impl<T> fmt::Debug for TimerHandle<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("TimerHandle")
            .field("ptr", &self.ptr)
            .finish()
    }
}