Struct MessageTimer

pub struct MessageTimer<T>
where
    T: 'static + Send + Clone,
{ /* private fields */ }

A monotonic timer, used to schedule delivery of messages at a later date.

In the current implementation, each timer is executed as two threads. The Scheduler thread is in charge of maintaining the queue of messages to deliver and of actually deliverying them. The Communication thread is in charge of communicating with the Scheduler thread (which requires acquiring a possibly-long-held Mutex) without blocking the caller thread.

Similar functionality could be implemented using the generic Timer type, however, using MessageTimer has two performance advantages over doing so. First, MessageTimer does not need to heap allocate a closure for each scheduled item, since the messages to queue are passed directly. Second, MessageTimer avoids the dynamic dispatch overhead associated with invoking the closure functions.

Implementations

impl<T> MessageTimer<T>

where T: 'static + Send + Clone,

pub fn new(tx: Sender<T>) -> Self

Create a message timer.

This immediately launches two threads, which will remain launched until the timer is dropped. As expected, the threads spend most of their life waiting for instructions.

pub fn with_capacity(tx: Sender<T>, capacity: usize) -> Self

As new(), but with a manually specified initial capacity.

pub fn schedule_with_delay(&self, delay: Duration, msg: T) -> Guard

Schedule a message for delivery after a delay.

Messages are guaranteed to never be delivered before the delay. However, it is possible that they will be delivered a little after the delay.

If the delay is negative or 0, the message is delivered as soon as possible.

This method returns a Guard object. If that Guard is dropped, delivery is cancelled.

Example

extern crate monotonic_timer;

use std::sync::mpsc::channel;
use std::time::Duration;

let (tx, rx) = channel();
let timer = monotonic_timer::MessageTimer::new(tx);
let _guard = timer.schedule_with_delay(Duration::from_secs(3), 3);

rx.recv().unwrap();
println!("This code has been executed after 3 seconds");

pub fn schedule_repeating(&self, repeat: Duration, msg: T) -> Guard

Schedule a message for delivery once per interval.

Messages are guaranteed to never be delivered before their date. However, it is possible that they will be delivered a little after it.

This method returns a Guard object. If that Guard is dropped, repeat is stopped.

Performance

The message is cloned on the Scheduler thread. Cloning of messages should therefore succeed very quickly, or risk delaying other messages.

Failures

Any failure in cloning of messages will occur on the scheduler thread and will contaminate the Timer and the calling thread itself. You have been warned.

Example

extern crate monotonic_timer;
use std::sync::mpsc::channel;
use std::time::Duration;

let (tx, rx) = channel();
let timer = monotonic_timer::MessageTimer::new(tx);

// Start repeating.
let guard = timer.schedule_repeating(Duration::from_millis(5), 0);

let mut count = 0;
while count < 5 {
  let _ = rx.recv();
  println!("Prints every 5 milliseconds");
  count += 1;
}

pub fn schedule<D>( &self, date: Instant, repeat: Option<Duration>, msg: T, ) -> Guard

Schedule a message for delivery at a given time, then once per interval. A typical use case is to execute code once per day at 12am.

Messages are guaranteed to never be delivered before their date. However, it is possible that they will be delivered a little after it.

This method returns a Guard object. If that Guard is dropped, repeat is stopped.

Performance

The message is cloned on the Scheduler thread. Cloning of messages should therefore succeed very quickly, or risk delaying other messages.

Failures

Any failure in cloning of messages will occur on the scheduler thread and will contaminate the Timer and the calling thread itself. You have been warned.