timer_deque_rs/timer_portable/

timer.rs

/*-
 * timer-rs - a Rust crate which provides timer and timer queues based on target OS
 *  functionality.
 * 
 * Copyright (C) 2025 Aleksandr Morozov
 * 
 * The timer-rs crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
 *                     
 *   2. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

use std::{borrow::Cow, cmp::Ordering, fmt, io::{self}};

use chrono::{DateTime, Local};
use nix::libc::{self, ECANCELED, EWOULDBLOCK};
use bitflags::bitflags;

use crate::timer_portable::portable_error::TimerPortResult;

#[cfg(target_os = "linux")]
pub use super::linux::timer_fd_linux::*;

#[cfg(any(
    target_os = "freebsd",
    target_os = "dragonfly",
    target_os = "netbsd",
    target_os = "openbsd",
    target_os = "macos",
))]
pub use super::bsd::timer_kqueue_bsd::*;


/// A timer type
#[allow(non_camel_case_types)]
#[derive(Debug)]
pub enum TimerType
{
    /// A settable system-wide real-time clock.
    CLOCK_REALTIME,

    /// A nonsettable monotonically increasing clock that measures  time
    /// from some unspecified point in the past that does not change af‐
    /// ter system startup.

    CLOCK_MONOTONIC,

    /// Like CLOCK_MONOTONIC, this is a monotonically increasing  clock.
    /// However,  whereas the CLOCK_MONOTONIC clock does not measure the
    /// time while a system is suspended, the CLOCK_BOOTTIME clock  does
    /// include  the time during which the system is suspended.  This is
    /// useful  for  applications  that  need   to   be   suspend-aware.
    /// CLOCK_REALTIME is not suitable for such applications, since that
    /// clock is affected by discontinuous changes to the system clock.
    CLOCK_BOOTTIME,

    /// This clock is like CLOCK_REALTIME, but will wake the  system  if
    /// it  is suspended.  The caller must have the CAP_WAKE_ALARM capa‐
    /// bility in order to set a timer against this clock.
    CLOCK_REALTIME_ALARM,

    /// This clock is like CLOCK_BOOTTIME, but will wake the  system  if
    /// it  is suspended.  The caller must have the CAP_WAKE_ALARM capa‐
    /// bility in order to set a timer against this clock.
    CLOCK_BOOTTIME_ALARM,
}

impl Into<libc::clockid_t> for TimerType 
{
    fn into(self) -> libc::clockid_t
    {
        match self
        {
            Self::CLOCK_REALTIME        => return libc::CLOCK_REALTIME,
            Self::CLOCK_MONOTONIC       => return libc::CLOCK_MONOTONIC,
            #[cfg(target_os = "linux")]
            Self::CLOCK_BOOTTIME        => return libc::CLOCK_BOOTTIME,
            #[cfg(target_os = "linux")]
            Self::CLOCK_REALTIME_ALARM  => return libc::CLOCK_REALTIME_ALARM,
            #[cfg(target_os = "linux")]
            Self::CLOCK_BOOTTIME_ALARM  => return libc::CLOCK_BOOTTIME_ALARM,
            #[cfg(any(
                target_os = "freebsd",
                target_os = "dragonfly",
                target_os = "netbsd",
                target_os = "openbsd",
                target_os = "macos",
            ))]
            _ => return libc::CLOCK_REALTIME,
        }
    }
}

#[cfg(target_os = "linux")]
bitflags! {     
    /// Flags controling the type of the timer type.  
    #[derive(Default)] 
    pub struct TimerFlags: i32  
    {     
        /// Set the O_NONBLOCK file status flag on the open file  de‐
        /// scription  (see  open(2)) referred to by the new file de‐
        /// scriptor.  Using this flag saves extra calls to  fcntl(2)
        /// to achieve the same result.
        const TFD_NONBLOCK = libc::TFD_NONBLOCK;

        /// Set  the  close-on-exec (FD_CLOEXEC) flag on the new file
        /// descriptor.  See the description of the O_CLOEXEC flag in
        /// open(2) for reasons why this may be useful.
        const TFD_CLOEXEC = libc::TFD_CLOEXEC;
    }
}

#[cfg(any(
    target_os = "freebsd",
    target_os = "dragonfly",
    target_os = "netbsd",
    target_os = "openbsd",
    target_os = "macos",
))]
bitflags! {     
    /// Flags controling the type of the timer type.   
    #[derive(Default)] 
    pub struct TimerFlags: i32  
    {     
        /// Not appliciable
        const TFD_NONBLOCK = 0;

        /// Not appliciable.
        const TFD_CLOEXEC = 0;
    }
}

#[cfg(target_os = "linux")]
bitflags! {     
    /// A bit mask that can include the values.
    #[derive(Default)] 
    pub struct TimerSetTimeFlags: i32  
    {     
        /// > Interpret  new_value.it_value as an absolute value on the timer's
        /// > clock.  The timer will expire when the value of the timer's clock
        /// > reaches the value specified in new_value.it_value.
        const TFD_TIMER_ABSTIME = libc::TFD_TIMER_ABSTIME;

        /// > If this flag is specified along with  TFD_TIMER_ABSTIME  and  the
        /// > clock  for  this timer is CLOCK_REALTIME or CLOCK_REALTIME_ALARM,
        /// > then mark this timer as cancelable if the real-time clock  under‐
        /// > goes  a  discontinuous change (settimeofday(2), clock_settime(2),
        /// > or similar).  When  such  changes  occur,  a  current  or  future
        /// > read(2)  from  the file descriptor will fail with the error 
        /// > ECANCELED.
        const TFD_TIMER_CANCEL_ON_SET = (1 << 1);
    }
}

#[cfg(any(
    target_os = "freebsd",
    target_os = "dragonfly",
    target_os = "netbsd",
    target_os = "openbsd",
    target_os = "macos",
))]

bitflags! {     
    /// A bit mask that can include the values. 
    #[derive(Default)] 
    pub struct TimerSetTimeFlags: i32  
    {     
        /// Not appliciable.
        const TFD_TIMER_ABSTIME = 0;

        /// Not appliciable.
        const TFD_TIMER_CANCEL_ON_SET = 0;
    }
}

/// A timer expiry modes. Not every OS supports 
/// every mode. Read comments for the OS specific
/// timer. For the `nanoseconds` param the max value
/// is 999_999_999 for most OSes.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TimerExpMode
{
    /// Disarmed
    None, 

    /// A timer which is triggered once.
    OneShot
    {
        /// Seconds
        sec: i64,

        /// Nanoseconds. 
        nsec: i64,
    },
    
    /// Interval with the initial delay.
    IntervalDelayed
    {
        /// First event delay seconds.
        delay_sec: i64, 

        /// First event delay nanoseconds. 
        delay_nsec: i64,

        /// Interval seconds.
        interv_sec: i64,

        /// Interval nanoseconds.
        interv_nsec: i64
    },

    /// Interval, with the first timeout event 
    /// equal to interval values.
    Interval
    {
        /// Interval seconds.
        sec: i64,

        /// Interval nanoseconds.
        nsec: i64,
    },
}

impl Ord for TimerExpMode
{
    fn cmp(&self, other: &Self) -> Ordering 
    {
        match (self, other)
        {
            (TimerExpMode::None, TimerExpMode::None) => 
                return Ordering::Equal,
            (TimerExpMode::OneShot{ sec, nsec }, TimerExpMode::OneShot { sec: sec2, nsec: nsec2 }) => 
            { 
                let s1 = sec.cmp(sec2);
                let s2 = nsec.cmp(nsec2);

                return s1.then(s2);
            },
            (
                TimerExpMode::IntervalDelayed
                    { delay_sec, delay_nsec, interv_sec, interv_nsec }, 
                TimerExpMode::IntervalDelayed 
                    { delay_sec: delay_sec2, delay_nsec: delay_nsec2, interv_sec: interv_sec2, interv_nsec: interv_nsec2 }) => 
            {
                return 
                    delay_sec.cmp(delay_sec2)
                        .then(delay_nsec.cmp(delay_nsec2)
                            .then(interv_sec.cmp(interv_sec2)
                                .then(interv_nsec.cmp(interv_nsec2))
                            )
                        );
            },
            (TimerExpMode::Interval { sec, nsec }, TimerExpMode::Interval { sec: sec2, nsec: nsec2 }) => 
            {
                return sec.cmp(sec2).then(nsec.cmp(nsec2));
            },
            _ => 
                panic!("cannot compare different types {} and {}", self, other)
        }
    }
}

impl PartialOrd for TimerExpMode
{
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> 
    {
        return Some(self.cmp(other));
    }
}


impl TimerExpMode
{
    /// Disarms the timer.
    pub 
    fn reset() -> Self
    {
        return Self::None;
    }

    /// Checks value for the `set_time` function. To disarm timer 
    /// use `unset_time`.
    pub 
    fn is_valid(&self) -> bool
    {
        match *self
        {
            Self::None => 
                return false,
            Self::OneShot{ sec, nsec } => 
                return sec != 0 || nsec != 0,
            Self::IntervalDelayed{ delay_sec, delay_nsec, interv_sec, interv_nsec} => 
                return (delay_sec != 0 || delay_nsec != 0) && (interv_sec != 0 || interv_nsec != 0),
            Self::Interval{ sec, nsec } => 
                return sec != 0 || nsec != 0
        }
    }
}

impl fmt::Display for TimerExpMode
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        match self
        {
            Self::None => 
                write!(f, "disarmed"),
            Self::OneShot{ sec, nsec } => 
                write!(f, "oneshot sec: {} nsec: {}", sec, nsec),
            Self::IntervalDelayed
                { delay_sec, delay_nsec, interv_sec, interv_nsec } => 
                write!(f, "interval sec: {} nsec: {} with delay sec: {} nsec: {}",
                    interv_sec, interv_nsec, delay_sec, delay_nsec),
            Self::Interval{ sec, nsec } => 
                write!(f, "interval sec: {} nsec: {}", sec, nsec),
        }
    }
}

#[cfg(any(
    target_os = "freebsd",
    target_os = "dragonfly",
    target_os = "netbsd",
    target_os = "openbsd",
    target_os = "macos",
    target_os = "linux",
))]
use nix::libc::{itimerspec, timespec};

#[cfg(target_os = "macos")]
#[repr(C)]
pub struct timespec 
{
    pub tv_sec: libc::time_t,
    pub tv_nsec: libc::c_long,
}
#[cfg(target_os = "macos")]
#[repr(C)]
pub struct itimerspec 
{
    pub it_interval: timespec,
    pub it_value: timespec,
}

impl From<DateTime<Local>> for TimerExpMode
{
    fn from(value: DateTime<Local>) -> Self 
    {
         return Self::OneShot { sec: value.timestamp(), nsec: value.timestamp_subsec_nanos() as i64 };
    }
}

impl From<itimerspec> for TimerExpMode
{
    fn from(value: itimerspec) -> Self 
    {
        if value.it_interval.tv_sec == 0 && value.it_interval.tv_nsec == 0 &&
            value.it_value.tv_sec == 0 && value.it_value.tv_nsec == 0
        {
            // unset
            return Self::None;
        }
        else if value.it_interval.tv_sec == 0 && value.it_interval.tv_nsec == 0
        {
            // one shot
            return Self::OneShot{ sec: value.it_interval.tv_sec, nsec: value.it_interval.tv_nsec };
        }
        else if value.it_interval.tv_sec == value.it_value.tv_sec &&
            value.it_interval.tv_nsec == value.it_value.tv_nsec
        {
            // interval
            return Self::Interval { sec: value.it_value.tv_sec, nsec: value.it_value.tv_nsec };
        }
        else
        {
            // delayed interval
            return 
                Self::IntervalDelayed 
                { 
                    delay_sec: value.it_value.tv_sec, 
                    delay_nsec: value.it_value.tv_nsec, 
                    interv_sec: value.it_interval.tv_sec, 
                    interv_nsec: value.it_interval.tv_nsec 
                };
        }
    }
}

impl From<TimerExpMode> for itimerspec
{
    fn from(value: TimerExpMode) -> Self 
    {
        match value
        {
            TimerExpMode::None => 
                return 
                    itimerspec 
                    {
                        it_interval: timespec 
                        {
                            tv_sec: 0,
                            tv_nsec: 0,
                        },
                        it_value: timespec
                        {
                            tv_sec: 0,
                            tv_nsec: 0,
                        },
                    },
            TimerExpMode::OneShot{ sec, nsec} =>
                return 
                    itimerspec 
                    {
                        it_interval: timespec 
                        {
                            tv_sec: 0,
                            tv_nsec: 0,
                        },
                        it_value: timespec
                        {
                            tv_sec: sec,
                            tv_nsec: nsec,
                        },
                    },
            TimerExpMode::IntervalDelayed 
                { delay_sec, delay_nsec, interv_sec, interv_nsec } => 
                return 
                    itimerspec 
                    {
                        it_interval: timespec 
                        {
                            tv_sec: interv_sec,
                            tv_nsec: interv_nsec,
                        },
                        it_value: timespec
                        {
                            tv_sec: delay_sec,
                            tv_nsec: delay_nsec,
                        },
                    },
            TimerExpMode::Interval{ sec, nsec } => 
                return 
                    itimerspec 
                    {
                        it_interval: timespec 
                        {
                            tv_sec: sec,
                            tv_nsec: nsec,
                        },
                        it_value: timespec
                        {
                            tv_sec: sec,
                            tv_nsec: nsec,
                        },
                    }
        }
    }
}

/// A timer FD read result.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TimerReadRes<T: Sized + fmt::Debug + fmt::Display + Clone + Eq + PartialEq>
{
    /// Read successfull.
    Ok(T),

    /// TFD_TIMER_ABSTIME 
    /// > Marks this timer as cancelable if the real-time clock  under‐
    /// > goes  a  discontinuous change (settimeofday(2), clock_settime(2),
    /// > or similar).  When  such  changes  occur,  a  current  or  future
    /// > read(2)  from  the file descriptor will fail with the error 
    /// > ECANCELED.
    Cancelled,

    /// EAGAIN
    /// If FD is nonblocking then this will be returned.
    WouldBlock,
}

impl TimerReadRes<u64>
{
    pub 
    fn ok() -> Self
    {
        return Self::Ok(1);
    }
}

impl<T: Sized + fmt::Debug + fmt::Display + Clone + Eq + PartialEq> From<io::Error> for TimerReadRes<T>
{
    fn from(value: io::Error) -> Self 
    {
        if let Some(errn) = value.raw_os_error()
        {
            if errn == ECANCELED
            {
                return Self::Cancelled;
            }
            else if errn == EWOULDBLOCK
            {
                return Self::WouldBlock;
            }
        }

        return Self::Cancelled;
    }
}

impl<T: Sized + fmt::Debug + fmt::Display + Clone + Eq + PartialEq> fmt::Display for TimerReadRes<T>
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        match self
        {
            Self::Ok(ovfl) => 
                write!(f, "OK(overflows:{})", ovfl),
            Self::Cancelled => 
                write!(f, "CANCELLED"),
            Self::WouldBlock => 
                write!(f, "WOULDBLOCK"),
        }
    }
}

impl<T: Sized + fmt::Debug + fmt::Display + Clone + Eq + PartialEq> TimerReadRes<T>
{
    pub 
    fn unwrap(self) -> T
    {
        let Self::Ok(t) = self
        else { panic!("can not unwrap {:?}", self)};

        return t;
    }
}

/// A common trait which is implemented by all timer realizationss for different OSes.
pub trait FdTimerCom
{
    /// Creates new isntance of the timer.
    /// 
    /// # Arguments
    /// 
    /// * `label` - a [Cow] string which defines a title of the timer for identification.
    /// 
    /// * `timer_type` - a [TimerType] a clock source
    /// 
    /// * `timer_flags` - a [TimerFlags] configuration of the timer's FD.
    /// 
    /// # Returns
    /// 
    /// A [Result] is retuned with instance on success.
    fn new(label: Cow<'static, str>, timer_type: TimerType, timer_flags: TimerFlags) -> TimerPortResult<Self>
    where Self: Sized;

    /// Attempts to read the timer. The realization is different on different OS. The main purpose 
    /// is to check if timer is ready (ended).
    fn read(&self) -> TimerPortResult<TimerReadRes<u64>>;

    /// The same as `read` but the buffer is external. The amount of read bytes are returned as
    /// a result.
    fn read_buf(&self, unfilled: &mut [u8]) -> std::io::Result<usize>;

    /// Sets the timer. The timer starts immidiatly.
    fn set_time(&self, flags: TimerSetTimeFlags, timer_exp: TimerExpMode) -> TimerPortResult<()>;

    /// Unsets the timer. The timer stops immidiatly.
    fn unset_time(&self) -> TimerPortResult<()>;
}


#[cfg(test)]
mod tests
{

    use crate::{common, timer_portable::timer::TimerExpMode};

    #[test]
    fn test_0() 
    {
        let ts = common::get_current_timestamp();

        let texp1 = TimerExpMode::from(ts);

        assert_eq!(
            TimerExpMode::OneShot { sec: ts.timestamp(), nsec: ts.timestamp_subsec_nanos() as i64 },
            texp1
        );
        
    }

    #[test]
    fn test_1() 
    {
        let ts = common::get_current_timestamp();

        let texp1 = TimerExpMode::from(ts);
        let texp2 = TimerExpMode::OneShot { sec: ts.timestamp()+1, nsec: ts.timestamp_subsec_nanos() as i64 };

        assert_eq!(texp1 < texp2, true);
        assert_eq!(texp2 > texp1, true);
        assert_eq!(texp2 != texp1, true);
        assert_eq!(texp2 < texp1, false);
    }

    #[test]
    fn test_2() 
    {
        let ts = common::get_current_timestamp();

        let texp1 = TimerExpMode::from(ts);
        let (sec, nanos) = 
            if ts.timestamp_subsec_nanos() == 999_999_999
            {
                (ts.timestamp()+1, 0)
            }
            else
            {
                (ts.timestamp(), ts.timestamp_subsec_nanos() + 1)
            };
        let texp2 = TimerExpMode::OneShot { sec: sec, nsec: nanos as i64 };

        assert_eq!(texp1 < texp2, true);
        assert_eq!(texp2 > texp1, true);
        assert_eq!(texp2 != texp1, true);
        assert_eq!(texp2 < texp1, false);
    }

    #[should_panic]
    #[test]
    fn test_2_fail() 
    {
        let ts = common::get_current_timestamp();

        let texp1 = TimerExpMode::from(ts);
        let texp2 = TimerExpMode::Interval { sec: 4, nsec: 4 };

        assert_eq!(texp1 < texp2, true);
    }
}