Struct timer::MessageTimer

pub struct MessageTimer<T> where T: 'static + Send + Clone {
    // some fields omitted
}

A 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.

Methods

impl<T> MessageTimer<T> where T: 'static + Send + Clone

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

Create a message timer.

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

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

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

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 timer;
extern crate chrono;
use std::sync::mpsc::channel;

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

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

fn schedule_with_date<D>(&self, date: DateTime<D>, msg: T) -> Guard where D: TimeZone

Schedule a message for delivery at a given date.

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

If the date is in the past, the message is delivered as soon as possible.

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

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 timer;
extern crate chrono;
use std::sync::mpsc::channel;

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

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

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

fn schedule<D>(&self, date: DateTime<D>, repeat: Option<Duration>, msg: T) -> Guard where D: TimeZone

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.