windows_win/raw/
timer.rs

1//! Windows timers API
2use crate::sys::{
3    QueryPerformanceFrequency,
4    QueryPerformanceCounter,
5    LARGE_INTEGER,
6    CreateTimerQueue,
7    CreateTimerQueueTimer,
8    DeleteTimerQueueEx,
9    DeleteTimerQueueTimer,
10    ChangeTimerQueueTimer,
11    HANDLE,
12    INVALID_HANDLE_VALUE,
13    WT_EXECUTEINTIMERTHREAD,
14    WT_EXECUTEINPERSISTENTTHREAD,
15    WT_EXECUTELONGFUNCTION,
16    WT_EXECUTEONLYONCE,
17    WT_TRANSFER_IMPERSONATION,
18    WAITORTIMERCALLBACK,
19    c_int,
20    c_ulong,
21    c_void,
22};
23use crate::utils::{self, Result};
24
25use core::{ptr, mem};
26
27///Retrieves the frequency of the performance counter.
28///
29///The frequency of the performance counter is fixed at system boot and is consistent across all processors.
30///Therefore, the frequency need only be queried upon application initialization, and the result can be cached.
31pub fn query_performance_frequency() -> Result<i64> {
32    let mut counter: LARGE_INTEGER = unsafe { mem::zeroed() };
33
34    unsafe {
35        match QueryPerformanceFrequency(&mut counter as *mut _) {
36            0 => Err(utils::get_last_error()),
37            _ => Ok(counter.QuadPart)
38        }
39    }
40}
41
42///Retrieves the current value of the performance counter, which is a high resolution (<1us) time
43///stamp that can be used for time-interval measurements.
44pub fn query_performance_counter() -> Result<i64> {
45    let mut counter: LARGE_INTEGER = unsafe { mem::zeroed() };
46
47    unsafe {
48        match QueryPerformanceCounter(&mut counter as *mut _) {
49            0 => Err(utils::get_last_error()),
50            _ => Ok(counter.QuadPart)
51        }
52    }
53}
54
55///Describes how to delete timer/queue
56pub trait CompleteEvent {
57    #[doc(hidden)]
58    fn handle() -> HANDLE;
59}
60
61///Schedules delete and exit immediately
62pub struct NoWait;
63impl CompleteEvent for NoWait {
64    fn handle() -> HANDLE {
65        ptr::null_mut()
66    }
67}
68
69///Waits for all callback functions to finish
70pub struct Wait;
71impl CompleteEvent for Wait {
72    fn handle() -> HANDLE {
73        INVALID_HANDLE_VALUE
74    }
75}
76
77#[derive(Copy, Clone)]
78///Describes timer flags
79pub struct TimerFlags {
80    inner: c_ulong
81}
82
83///Default timer flags to only execute callback on non-IO thread
84pub const DEFAULT_TIMER_FLAGS: TimerFlags = TimerFlags {
85    inner: 0
86};
87
88impl TimerFlags {
89    ///Creates new instance of default flags
90    pub fn new() -> Self {
91        DEFAULT_TIMER_FLAGS
92    }
93
94    ///The callback function is invoked by the timer thread itself.
95    ///
96    ///This flag should be used only for short tasks or it could affect other timer operations.
97    pub fn on_timer_thread(mut self) -> Self {
98        self.inner |= WT_EXECUTEINTIMERTHREAD;
99        self
100    }
101
102    ///The callback function is queued to a thread that never terminates.
103    ///
104    ///It does not guarantee that the same thread is used each time.
105    ///This flag should be used only for short tasks or it could affect other timer operations.
106    pub fn on_persist(mut self) -> Self {
107        self.inner |= WT_EXECUTEINPERSISTENTTHREAD;
108        self
109    }
110
111    ///The callback function can perform a long wait.
112    ///
113    ///This flag helps the system to decide if it should create a new thread.
114    pub fn long_fn(mut self) -> Self {
115        self.inner |= WT_EXECUTELONGFUNCTION;
116        self
117    }
118
119    ///The timer will be set to the signaled state only once.
120    ///
121    ///If this flag is set, the Period parameter must not be set.
122    pub fn only_once(mut self) -> Self {
123        self.inner |= WT_EXECUTEONLYONCE;
124        self
125    }
126
127    ///Callback functions will use the current access token, whether it is a process or
128    ///impersonation token.
129    ///
130    ///If this flag is not specified, callback functions execute only with the
131    ///process token.
132    pub fn transfer_impersonation(mut self) -> Self {
133        self.inner |= WT_TRANSFER_IMPERSONATION;
134        self
135    }
136}
137
138///Queue for timer
139///
140///By default `Drop` implementation deletes timer without waiting for
141///queue to finish currently executing callbacks.
142///If you want to wait then you can use `delete` method.
143///
144///Alternatively you can use default system queue by accessing `DEFAULT_TIMER_QUEUE`
145///In this case it is impossible to delete queue and `delete` always returns `Ok`
146pub struct TimerQueue {
147    handle: HANDLE
148}
149
150impl TimerQueue {
151    ///Creates new instance of queue
152    pub fn new() -> Result<Self> {
153        let handle = unsafe { CreateTimerQueue() };
154
155        match handle.is_null() {
156            true => Err(utils::get_last_error()),
157            false => Ok(Self { handle })
158        }
159    }
160
161    #[inline]
162    fn inner_delete<T: CompleteEvent>(&self) -> c_int {
163        match self.handle.is_null() {
164            true => 1,
165            false => unsafe { DeleteTimerQueueEx(self.handle, T::handle()) },
166        }
167    }
168
169    ///Deletes queue and consumes it.
170    ///
171    ///Note that it invalidates all timers produced by it.
172    pub fn delete<T: CompleteEvent>(self, _event: T) -> Result<()> {
173        let result = match self.inner_delete::<T>() {
174            0 => Err(utils::get_last_error()),
175            _ => Ok(())
176        };
177
178        mem::forget(self);
179        result
180    }
181
182    ///Creates new timer on queue.
183    ///
184    ///## Parameters
185    ///
186    ///- `cb` - C function to be executed.
187    ///- `param` - Pointer to callback parameter.
188    ///- `due_time` - The amount of time in milliseconds relative to the current time that must elapse before the timer is signaled for the first time.
189    ///- `period` - The period of the timer, in milliseconds. If this parameter is zero, the timer is signaled once. If this parameter is greater than zero, the timer is periodic. A periodic timer automatically reactivates each time the period elapses, until the timer is canceled.
190    ///- `flags` - Timer flags
191    pub fn timer(&self, cb: WAITORTIMERCALLBACK, param: *mut c_void, due_time: c_ulong, period: c_ulong, flags: TimerFlags) -> Result<QueueTimer> {
192        let mut timer: *mut c_void = ptr::null_mut();
193
194        match unsafe { CreateTimerQueueTimer(&mut timer as *mut _, self.handle, cb, param, due_time, period, flags.inner) } {
195            0 => Err(utils::get_last_error()),
196            _ => Ok(QueueTimer { queue: self.handle, inner: timer })
197        }
198    }
199}
200
201///Raw type of callback function
202pub type CallbackType = WAITORTIMERCALLBACK;
203
204///Default Timer queue
205pub const DEFAULT_TIMER_QUEUE: TimerQueue = TimerQueue {
206    handle: ptr::null_mut()
207};
208
209impl Default for TimerQueue {
210    fn default() -> Self {
211        DEFAULT_TIMER_QUEUE
212    }
213}
214
215impl Drop for TimerQueue {
216    fn drop(&mut self) {
217        let _ = self.inner_delete::<NoWait>();
218    }
219}
220
221unsafe impl Send for TimerQueue {}
222unsafe impl Sync for TimerQueue {}
223
224///Timer that schedules callback on thread pool
225///
226///By default `Drop` implementation deletes queue without waiting for
227///callback to be finished.
228///If you want to wait then you can use `delete` method.
229pub struct QueueTimer {
230    queue: HANDLE,
231    inner: HANDLE,
232}
233
234impl QueueTimer {
235    #[inline]
236    fn inner_delete<T: CompleteEvent>(&self) -> c_int {
237        unsafe { DeleteTimerQueueTimer(self.queue, self.inner, T::handle()) }
238    }
239
240    ///Cancels timer without consuming it
241    ///
242    ///User must ensure that drop is not called by forgetting timer
243    pub unsafe fn cancel<T: CompleteEvent>(&self, _event: T) -> Result<()> {
244        match self.inner_delete::<T>() {
245            0 => Err(utils::get_last_error()),
246            _ => Ok(())
247        }
248    }
249
250    ///Resets timer with new values of due_time and period
251    ///
252    ///Note: if you call it on a one-shot timer (its period is zero) that has already expired, the timer is not
253    ///updated.
254    pub fn reset(&self, due_time: c_ulong, period: c_ulong) -> Result<()> {
255        match unsafe { ChangeTimerQueueTimer(self.queue, self.inner, due_time, period) } {
256            0 => Err(utils::get_last_error()),
257            _ => Ok(())
258        }
259    }
260
261    ///Deletes timer and consumes it.
262    pub fn delete<T: CompleteEvent>(self, event: T) -> Result<()> {
263        let result = unsafe { self.cancel(event) };
264
265        mem::forget(self);
266        result
267    }
268}
269
270impl Drop for QueueTimer {
271    fn drop(&mut self) {
272        let _ = self.inner_delete::<NoWait>();
273    }
274}
275
276unsafe impl Send for QueueTimer {}
277unsafe impl Sync for QueueTimer {}
windows_win/raw/timer.rs

windows_win/raw/
timer.rs
