Struct tokio::runtime::time::entry::StateCell

pub(super) struct StateCell {
    state: AtomicU64,
    result: UnsafeCell<Result<(), Error>>,
    waker: AtomicWaker,
}

This structure holds the current shared state of the timer - its scheduled time (if registered), or otherwise the result of the timer completing, as well as the registered waker.

Generally, the StateCell is only permitted to be accessed from two contexts: Either a thread holding the corresponding &mut TimerEntry, or a thread holding the timer driver lock. The write actions on the StateCell amount to passing “ownership” of the StateCell between these contexts; moving a timer from the TimerEntry to the driver requires both holding the &mut TimerEntry and the driver lock, while moving it back (firing the timer) requires only the driver lock.

Fields

state: AtomicU64

Holds either the scheduled expiration time for this timer, or (if the timer has been fired and is unregistered), u64::MAX.

result: UnsafeCell<Result<(), Error>>

If the timer is fired (an Acquire order read on state shows u64::MAX), holds the result that should be returned from polling the timer. Otherwise, the contents are unspecified and reading without holding the driver lock is undefined behavior.

waker: AtomicWaker

The currently-registered waker

Implementations

impl StateCell

fn new() -> Self

fn is_pending(&self) -> bool

fn when(&self) -> Option<u64>

Returns the current expiration time, or None if not currently scheduled.

fn poll(&self, waker: &Waker) -> Poll<Result<(), Error>>

If the timer is completed, returns the result of the timer. Otherwise, returns None and registers the waker.

fn read_state(&self) -> Poll<Result<(), Error>>

unsafe fn mark_pending(&self, not_after: u64) -> Result<(), u64>

Marks this timer as being moved to the pending list, if its scheduled time is not after not_after.

If the timer is scheduled for a time after not_after, returns an Err containing the current scheduled time.

SAFETY: Must hold the driver lock.

unsafe fn fire(&self, result: Result<(), Error>) -> Option<Waker>

Fires the timer, setting the result to the provided result.

Returns:

• Some(waker) - if fired and a waker needs to be invoked once the driver lock is released
• None - if fired and a waker does not need to be invoked, or if already fired

SAFETY: The driver lock must be held.

fn set_expiration(&self, timestamp: u64)

Marks the timer as registered (poll will return None) and sets the expiration time.

While this function is memory-safe, it should only be called from a context holding both &mut TimerEntry and the driver lock.

fn extend_expiration(&self, new_timestamp: u64) -> Result<(), ()>

Attempts to adjust the timer to a new timestamp.

If the timer has already been fired, is pending firing, or the new timestamp is earlier than the old timestamp, (or occasionally spuriously) returns Err without changing the timer’s state. In this case, the timer must be deregistered and re-registered.

pub(super) fn might_be_registered(&self) -> bool

Returns true if the state of this timer indicates that the timer might be registered with the driver. This check is performed with relaxed ordering, but is conservative - if it returns false, the timer is definitely not registered.

Trait Implementations

impl Debug for StateCell

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for StateCell

fn default() -> Self

Returns the “default value” for a type.