Struct native_timer::TimerQueue

pub struct TimerQueue(_);

TimerQueue manages scheduling of timers. Timer can be created from TimerQueue only.

Implementation of TimerQueue in Windows OS uses Win32 API Timer Queues.

In Unix platforms, TimerQueue use POSIX timer_create API to schedule signal in a dedicated thread and dispatch task executions depending on the task’s hint. That is, for any quick function handler, it will be called from another common, dedicated thread. For the slow function handler, each execution will be on its own thread.

TimerQueue has a default queue which can be used right away. But if you need to have another set of working threads, you can use TimerQueue::new too.

Example

use native_timer::TimerQueue;

let mut count = 0;
let default_queue = TimerQueue::default();  // you can use TimerQueue::new() too.
let t = default_queue.schedule_timer(Duration::from_millis(100), Duration::default(), 
                                     None, || count += 1);
sleep(Duration::from_millis(200));
drop(t);
assert_eq!(count, 1);

Implementations

impl TimerQueue

pub fn new() -> Self

Create a new TimerQueue

pub fn default() -> &'static TimerQueue

Default OS common timer queue

pub fn schedule_timer<'h, F>(
    &self,
    due: Duration,
    period: Duration,
    hint: Option<CallbackHint>,
    handler: F
) -> Result<Timer<'h>>where
    F: FnMut() + Send + 'h,

Schedule a timer, either a one-shot timer, or a periodical timer.

Arguments

• due: Due time to execute the task
• period: Time interval to repeat the task
• hint: Behavior hint of handler, which impacts how the task will be scheduled
• handler: The task to be called back

returns: Result<Timer, TimerError>

Examples

Single-shot timer

use native_timer::TimerQueue;

let my_queue = TimerQueue::new();
let mut called = 0;
let timer = my_queue.schedule_timer(Duration::from_millis(400), Duration::ZERO,
                                    None, || called += 1).unwrap();
thread::sleep(Duration::from_secs(1));
drop(timer);
assert_eq!(called, 1);

Periodical timer

use native_timer::TimerQueue;

let my_queue = TimerQueue::new();
let mut called = 0;
let duration = Duration::from_millis(300);
let t = my_queue.schedule_timer(duration, duration, None, || called += 1).unwrap();
thread::sleep(Duration::from_secs(1));
drop(t);
assert_eq!(called, 3);

pub fn schedule_oneshot<'h, F>(
    &self,
    due: Duration,
    hint: Option<CallbackHint>,
    handler: F
) -> Result<Timer<'h>>where
    F: FnOnce() + Send + 'h,

Schedule an one-shot timer. This is different from schedule_timer that this function’s handler is FnOnce. Parameter period is also not needed here.

Arguments

• due: Due time to execute the task
• hint: Behavior hint of handler, which impacts how the task will be scheduled
• handler: The task to be called back

returns: Result<Timer, TimerError>

Examples

use native_timer::TimerQueue;

let my_queue = TimerQueue::new();
let mut called = 0;
let timer = my_queue.schedule_oneshot(Duration::from_millis(400), None,
                                   || called += 1).unwrap();
thread::sleep(Duration::from_secs(1));
drop(timer);
assert_eq!(called, 1);

pub fn fire_oneshot<F>(
    &self,
    due: Duration,
    hint: Option<CallbackHint>,
    handler: F
) -> Result<()>where
    F: FnOnce() + Send + 'static,

Schedule an one-shot of the task. Note that this fire_oneshot requires a 'static lifetime closure.

Arguments

• due: Due time to execute the task
• hint: Behavior hint of handler, which impacts how the task will be scheduled
• handler: The task to be called back

returns: Result<(), TimerError>

Examples

This example creates a new TimerQueue to show that the lifetime of the queue is irrelevant. But in actual usage, you can simply use TimerQueue::default.

use native_timer::TimerQueue;

let flag = Arc::new(AtomicBool::new(false));
let flag_writer = flag.clone();
TimerQueue::new().fire_oneshot(Duration::from_millis(100), 
                                   None, move || flag_writer.store(true, Ordering::SeqCst)).unwrap();
thread::sleep(Duration::from_millis(200));
assert!(flag.load(Ordering::SeqCst));