Introduce timer_* support

This commit adds support for the signal timer mechanism in POSIX, the
mirror to timerfd on Linux. I wasn't _quite_ sure of how to fit into
the project organization but hopefully this commit isn't too far off.

Resolves nix-rust#1424

Signed-off-by: Brian L. Troutwine <[email protected]>

Author: blt

src/lib.rs

@@ -143,6 +143,10 @@ feature! {
     #[allow(missing_docs)]
     pub mod time;
 }
+feature! {
+    #![feature = "time"]
+    pub mod timer;
+}
 // This can be implemented for other platforms as soon as libc
 // provides bindings for them.
 #[cfg(all(target_os = "linux",

src/sys/signal.rs

@@ -1085,6 +1085,11 @@ mod sigevent {
         pub fn sigevent(&self) -> libc::sigevent {
             self.sigevent
         }
+
+        /// Returns a mutable pointer to the `sigevent` wrapped by `self`
+        pub fn as_raw_mut(&mut self) -> *mut libc::sigevent {
+            &mut self.sigevent
+        }
     }
 
     impl<'a> From<&'a libc::sigevent> for SigEvent {

src/sys/timerfd.rs

@@ -85,7 +85,7 @@ bitflags! {
 }
 
 #[derive(Debug, Clone, Copy)]
-struct TimerSpec(libc::itimerspec);
+pub(crate) struct TimerSpec(libc::itimerspec);
 
 impl TimerSpec {
     pub const fn none() -> Self {
@@ -102,6 +102,12 @@ impl TimerSpec {
     }
 }
 
+impl AsMut<libc::itimerspec> for TimerSpec {
+    fn as_mut(&mut self) -> &mut libc::itimerspec {
+        &mut self.0
+    }
+}
+
 impl AsRef<libc::itimerspec> for TimerSpec {
     fn as_ref(&self) -> &libc::itimerspec {
         &self.0

src/timer.rs

@@ -0,0 +1,116 @@
+//! Timer API via signals.
+//!
+//! Timer is a POSIX API to create timers and get expiration notifications
+//! through signals.
+//!
+//! For more documentation, please read [timer_create(3p)](https://man7.org/linux/man-pages/man3/timer_create.3p.html).
+use crate::sys::timerfd::{TimerSetTimeFlags, TimerSpec};
+use crate::sys::{signal::SigEvent, timerfd::Expiration};
+use crate::time::ClockId;
+use crate::{errno::Errno, Result};
+use core::mem;
+
+/// The maximum value that [`Timer::overruns`] will return.
+pub const DELAYTIMER_MAX: i32 = libc::_SC_DELAYTIMER_MAX as i32;
+
+/// A per-process timer
+#[derive(Debug)]
+pub struct Timer {
+    timer_id: libc::timer_t,
+}
+
+impl Timer {
+    /// Creates a new timer based on the clock defined by `clockid`. The details
+    /// of the signal and its handler are defined by the passed `sigevent`.
+    pub fn new(clockid: ClockId, mut sigevent: SigEvent) -> Result<Self> {
+        let mut timer_id: libc::timer_t = unsafe { mem::zeroed::<libc::timer_t>() };
+        Errno::result(unsafe {
+            libc::timer_create(clockid.as_raw(), sigevent.as_raw_mut(), &mut timer_id)
+        })
+        .map(|_| Self { timer_id })
+    }
+
+    /// Set a new alarm on the timer.
+    ///
+    /// # Types of alarm
+    ///
+    /// There are 3 types of alarms you can set:
+    ///
+    ///   - one shot: the alarm will trigger once after the specified amount of
+    /// time.
+    ///     Example: I want an alarm to go off in 60s and then disables itself.
+    ///
+    ///   - interval: the alarm will trigger every specified interval of time.
+    ///     Example: I want an alarm to go off every 60s. The alarm will first
+    ///     go off 60s after I set it and every 60s after that. The alarm will
+    ///     not disable itself.
+    ///
+    ///   - interval delayed: the alarm will trigger after a certain amount of
+    ///     time and then trigger at a specified interval.
+    ///     Example: I want an alarm to go off every 60s but only start in 1h.
+    ///     The alarm will first trigger 1h after I set it and then every 60s
+    ///     after that. The alarm will not disable itself.
+    ///
+    /// # Relative vs absolute alarm
+    ///
+    /// If you do not set any `TimerSetTimeFlags`, then the `TimeSpec` you pass
+    /// to the `Expiration` you want is relative. If however you want an alarm
+    /// to go off at a certain point in time, you can set `TFD_TIMER_ABSTIME`.
+    /// Then the one shot TimeSpec and the delay TimeSpec of the delayed
+    /// interval are going to be interpreted as absolute.
+    ///
+    /// # Disabling alarms
+    ///
+    /// Note: Only one alarm can be set for any given timer. Setting a new alarm
+    /// actually removes the previous one.
+    ///
+    /// Note: Setting a one shot alarm with a 0s TimeSpec disables the alarm
+    /// altogether.
+    pub fn set(&mut self, expiration: Expiration, flags: TimerSetTimeFlags) -> Result<()> {
+        let timerspec: TimerSpec = expiration.into();
+        Errno::result(unsafe {
+            libc::timer_settime(
+                self.timer_id,
+                flags.bits(),
+                timerspec.as_ref(),
+                core::ptr::null_mut(),
+            )
+        })
+        .map(drop)
+    }
+
+    /// Get the parameters for the alarm currently set, if any.
+    pub fn get(&self) -> Result<Option<Expiration>> {
+        let mut timerspec = TimerSpec::none();
+        Errno::result(unsafe { libc::timer_gettime(self.timer_id, timerspec.as_mut()) }).map(|_| {
+            if timerspec.as_ref().it_interval.tv_sec == 0
+                && timerspec.as_ref().it_interval.tv_nsec == 0
+                && timerspec.as_ref().it_value.tv_sec == 0
+                && timerspec.as_ref().it_value.tv_nsec == 0
+            {
+                None
+            } else {
+                Some(timerspec.into())
+            }
+        })
+    }
+
+    /// Return the number of timers that have overrun
+    ///
+    /// An overrun timer is one which expires while its related signal is still
+    /// queued. TODO explain better
+    pub fn overruns(&self) -> i32 {
+        unsafe { libc::timer_getoverrun(self.timer_id) }
+    }
+}
+
+impl Drop for Timer {
+    fn drop(&mut self) {
+        if !std::thread::panicking() {
+            let result = Errno::result(unsafe { libc::timer_delete(self.timer_id) });
+            if let Err(Errno::EINVAL) = result {
+                panic!("close of Timer encountered EINVAL");
+            }
+        }
+    }
+}