Struct Timer

pub(crate) struct Timer<R: SleepProvider> {
    sleep_prov: R,
    parameters: Option<PreparedParameters>,
    selected_timeout: Option<Duration>,
    trigger_at: Option<Instant>,
    waker: Option<R::SleepFuture>,
}

Timer that organises wakeups when channel padding should be sent

Use next() to find when to send padding, and note_cell_sent() to reset the timeout when data flows.

A Timer can be in “disabled” state, in which case next() never completes.

Timer must be pinned before use (this allows us to avoid involving the allocator when we reschedule).

Fields

sleep_prov: R

[SleepProvider]

parameters: Option<PreparedParameters>

Parameters controlling distribution of padding time intervals

Can be None to mean the timing parameters are set to infinity.

selected_timeout: Option<Duration>

Gap that we intend to leave between last sent cell, and the padding

We only resample this (calculating a new random delay) after the previous timeout actually expired.

None if the timer is disabled. (This can be done explicitly, but also occurs on time calculation overflow.)

Invariants: this field may be Some or None regardless of the values of other fields. If this field is None then the values in trigger_at and waker are unspecified.

trigger_at: Option<Instant>

Absolute time at which we should send padding

None if cells more recently sent than we were polled. That would mean that we are currently moving data out through this channel. The absolute timeout will need to be recalculated when the data flow pauses.

Some means our next has been demanded recently. Then trigger_at records the absolute timeout at which we should send padding, which was calculated the first time we were polled (after data).

Invariants: the value in this field is meaningful only if selected_timeout is Some.

If selected_timeout is Some, and trigger_at is therefore valid, it is (obviously) no later than selected_timeout from now.

See also waker.

waker: Option<R::SleepFuture>

Actual waker from the SleepProvider

This is created and updated lazily, because we suspect that with some runtimes setting timeouts may be slow. Lazy updating means that with intermittent data traffic, we do not keep scheduling, descheduling, and adjusting, a wakeup time.

Invariants:

If selected_timeout is Some, the time at which this waker will trigger here is never later than trigger_at, and never later than selected_timeout from now.

The wakeup time here may well be earlier than trigger_at, and sooner than selected_timeout from now. It may even be in the past. When we wake up and discover this situation, we reschedule a new waker.

If selected_timeout is None, the value is unspecified. We may retain a Some in this case so that if SleepProvider is enhanced to support rescheduling, we can do that without making a new SleepFuture (and without completely reorganising this the Timer state structure.)

Implementations

impl<R: SleepProvider> Timer<R>

pub(crate) fn project<'pin>( self: Pin<&'pin mut Self>, ) -> PaddingTimerProj<'pin, R>

pub(crate) fn project_ref<'pin>( self: Pin<&'pin Self>, ) -> __TimerProjectionRef<'pin, R>

impl<R: SleepProvider> Timer<R>

pub(crate) fn new(sleep_prov: R, parameters: Parameters) -> Result<Self>

Create a new Timer

pub(crate) fn new_disabled( sleep_prov: R, parameters: Option<Parameters>, ) -> Result<Self>

Create a new Timer which starts out disabled

pub(crate) fn disable(self: &mut Pin<&mut Self>)

Disable this Timer

Idempotent.

pub(crate) fn enable(self: &mut Pin<&mut Self>)

Enable this Timer

(If the timer was disabled, the timeout will only start to run when next() is next polled.)

Idempotent.

pub(crate) fn reconfigure( self: &mut Pin<&mut Self>, parameters: &Parameters, ) -> Result<()>

Set this Timer’s parameters

Will not enable or disable the timer; that must be done separately if desired.

The effect may not be immediate: if we are already in a gap between cells, that existing gap may not be adjusted. (We don’t restart the timer since that would very likely result in a gap longer than either of the configured values.)

Idempotent.

pub(crate) fn is_enabled(&self) -> bool

Enquire whether this Timer is currently enabled

fn select_fresh_timeout(self: Pin<&mut Self>)

Select a fresh timeout (and enable, if possible)

pub(crate) fn note_cell_sent(self: &mut Pin<&mut Self>)

Note that data has been sent (ie, reset the timeout, delaying the next padding)

fn prepare_to_sleep( self: Pin<&mut Self>, now: Option<Instant>, ) -> SleepInstructions<'_, R>

Calculate when to send padding, and return a suitable waker

In the usual case returns SleepInstructions::Waker.

pub(crate) fn next( self: Pin<&mut Self>, ) -> impl FusedFuture<Output = Padding> + '_

Wait until we should next send padding, and then return the padding message

Should be used as a low-priority branch within select_biased!.

(next() has to be selected on, along with other possible events, in the main loop, so that the padding timer runs concurrently with other processing; and it should be in a low-priority branch of select_biased! as an optimisation: that avoids calculating timeouts etc. until necessary, i.e. it calculates them only when the main loop would otherwise block.)

The returned future is async-cancel-safe, but once it yields, the padding must actually be sent.

async fn next_inner(self: Pin<&mut Self>) -> Padding

Wait until we should next send padding (not FusedFuture)

Callers wants a [FusedFuture] because select! needs one.

Trait Implementations

impl<'pin, R: SleepProvider> Unpin for Timer<R>

where PinnedFieldsOf<__Timer<'pin, R>>: Unpin,