timer_deque_rs/timer_portable/

poll.rs

/*-
 * timer-deque-rs - a Rust crate which provides timer and timer queues based on target OS
 *  functionality.
 * 
 * Copyright (C) 2025 Aleksandr Morozov alex@nixd.org
 *  4neko.org alex@4neko.org
 * 
 * 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::{fmt, mem::discriminant, ops, os::fd::{AsFd, RawFd}, sync::{Arc, Weak}};


use nix::{errno::Errno, sys::eventfd::EventFd};

use crate::
{
    error::{TimerError, TimerErrorType, TimerResult}, 
    map_timer_err, 
    timer_err, 
    timer_portable::DefaultEventWatch
};

/// Defines a result which may occure when polling the timer's FDs 
/// (for a single event).
#[derive(Debug)]
pub struct PollResult
{
    events: Vec<PollEventType>,
}

impl ops::Index<usize> for PollResult
{
    type Output = PollEventType;

    fn index(&self, index: usize) -> &Self::Output 
    {
        return &self.events[index];
    }
}

impl fmt::Display for PollResult
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        write!(f, "{:?}", self.events)
    }
}

impl PollResult
{
    #[inline]
    pub
    fn new_none() -> Self
    {
        return Self{ events: Vec::new()};
    }

    #[inline]
    pub 
    fn new(evs: usize) -> Self
    {
        return Self{ events: Vec::with_capacity(evs) };
    }

    #[inline]
    pub 
    fn push(&mut self, pet: PollEventType)
    {
        self.events.push(pet);
    }

    pub 
    fn is_none(&self) -> bool
    {
        return self.events.is_empty();
    }

    pub 
    fn len(&self) -> usize
    {
        return self.events.len();
    }

    pub 
    fn pop(&mut self) -> Option<PollEventType>
    {
        return self.events.pop();
    }

    pub 
    fn into_inner(self) -> Vec<PollEventType>
    {
        return self.events;
    }
}

/// Defines a result which may occure when polling the timer's FDs 
/// (for a multiple events).
#[derive(Debug, PartialEq, Eq)]
pub enum PollEventType
{
    /// Timer which generates time up event.
    Some(RawFd),

    /// Returned if timer (0 - [RawFd]) was removed.
    TimerRemoved(RawFd),

    /// Sub error which occured during `read()`.
    SubError(TimerError)
}

impl fmt::Display for PollEventType
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        match self
        {
            Self::Some(items) => 
                write!(f, "event fd: {:?}", items),
            Self::TimerRemoved(fd) => 
                write!(f, "timer {} removed", fd),
            Self::SubError(err) => 
                write!(f, "sub error: {}", err)
        }
    }
}

impl PollEventType
{
    pub 
    fn unwrap_some(self) -> RawFd
    {
        let Self::Some(rawfd) = self
            else
            {
                panic!("expected Some, got: {}", self)
            };

        return rawfd;
    }

    pub 
    fn is_some(&self) -> bool
    {
        return 
            discriminant(self) == discriminant(&Self::Some(0));
    }
}

/// A trait which is implemented by the timer instance which will be used by the 
/// [TimerPoll] to bind the timer.
pub trait AsTimerFd: fmt::Display + AsFd
{
    /// Should return the upgraded reference to which instance it is bind.
    /// 
    /// # Returns
    /// 
    /// A [Option] is returned where:
    /// 
    /// * [Option::Some] is returned if [Weak] to [Arc] was successfull or
    ///     the record is set.
    /// 
    /// * [Option::None] is returned if unset or upgrade failed. In case of latter, 
    ///     this should not happen if called from the same instance.
    fn get_bind(&self) -> Option<Arc<DefaultEventWatch>>;

    /// Regesters `poller` [DefaultEventWatch] on the timer's record.
    /// 
    /// # Arguments
    /// 
    /// * `timer_weak_ref` - a [Weak] reference to [Arc] of [DefaultEventWatch] of the 
    ///     current instance.
    fn bind_poll(&self, timer_weak_ref: Weak<DefaultEventWatch>);

    /// Removes bind fromt the timer.
    fn unbind_poll(&self);
}

/// A trait which is implemented by the poll instance in order for the timer 
/// instance to be able to unregister itself if the timer instance becomes invalid by accident 
/// or on purpose without removing it from the the [TimerPoll].
/// 
/// This is a subset of the [TimerPollOps] trait.
pub trait TimerPollOpsUnregister: fmt::Display
{
    /// Removes the specified timer `timer` (which must implement [AsTimerFd]) from
    /// the polling instance.
    fn unregister<T: AsTimerFd>(&self, timer: &T) -> TimerResult<()>;
}

/// A standart functions for each timer.
pub trait TimerPollOps: TimerPollOpsUnregister
{
    /// Creates new default instance.
    /// 
    /// # Returns
    /// 
    /// A [TimerResult] is returned with instance on success.
    fn new() -> TimerResult<Self> where Self: Sized;

    /// Adds the timer to the event monitor. It accepts any reference to instance which
    /// implements [AsFd] and it is not limited specificly to timers. Maybe later this
    /// behaviour will me modified.
    /// 
    /// # Arguments
    /// 
    /// * `timer` - `T` where impl [AsTimerFd] a timer instance. The provided
    ///     FD will be polled for [EpollFlags::EPOLLIN] event types. 
    /// 
    /// # Returns
    /// 
    /// A [TimerResult] i.e [Result] is returned with error description in case of error.
    fn add<T: AsTimerFd>(&self, timer: &T) -> TimerResult<()>;

    /// Removes the specific timer's FD from the event monitor.
    /// 
    /// # Arguments
    /// 
    /// * `timer` - `T` where impl [AsTimerFd] a timer instance. 
    /// 
    /// # Returns
    /// 
    /// A [TimerResult] i.e [Result] is returned with error description in case of error.
    fn delete<T: AsTimerFd>(&self, timer: &T) -> TimerResult<()>;

    /// Polls the event monitor for events. Depending on the `timeout` the behaviour will
    /// be different.
    /// 
    /// 
    /// # Arguments
    /// 
    /// * `timeout` - poll timeout. If set to [Option::None] will block the current thread.
    ///     If set to [Option::Some] with inner value `0` will return immidiatly. The 
    ///     timeout is set in `miliseconds`.
    /// 
    /// # Returns 
    /// 
    /// A [TimerResult] i.e [Result] is returned with
    /// 
    /// * [Result::Ok] with the [PollResult] where:
    /// 
    ///     * [PollResult::Some] with the [Vec] with the [RawFd] of the timer's where the event has
    ///         happened.
    /// 
    ///     * [PollResult::None] if no events happened.
    /// 
    ///     * [PollResult::TimerRemoved] if timer was removed during polling operation. Otherwise,
    ///         it will not be returned. If timer was cancelled and another timer times out, the 
    ///         `TimerRemoved` will be supressed in favor of the [PollResult::Some].
    /// 
    /// * [Result::Err] with error description.
    fn poll(&self, timeout: Option<i32>) -> TimerResult<PollResult>;

    /// Returns the amount of timer's FDs
    fn get_count(&self) -> usize;

    /// Provides a [Weak] reference to the wakeup [EventFd].
    fn get_poll_interruptor(&self) -> PollInterrupt;

    /// Attempts to interrupt the poll operaiton. If successfull returns `true`.
    fn interrupt_poll(&self) -> bool;
}

#[derive(Debug)]
pub struct PollInterruptAq(Arc<EventFd>);

impl PollInterruptAq
{
    pub 
    fn interrupt(&self) -> TimerResult<()>
    {
        return 
            self
                .0
                .write(1)
                .map_err(|e|
                    map_timer_err!(TimerErrorType::EPoll(e), "can not interrupt POLL!")
                )
                .map(|_| ());
    }

    pub 
    fn interrupt_drop(self) -> TimerResult<()>
    {
        return 
            self.interrupt();
    }
}

#[derive(Debug, Clone)]
pub struct PollInterrupt(Weak<EventFd>);

impl PollInterrupt
{
    pub 
    fn new(ev_weak: Weak<EventFd>) -> Self
    {
        return Self(ev_weak);
    }

    pub 
    fn aquire(&self) -> TimerResult<PollInterruptAq>
    {
        return 
            self
                .0
                .upgrade()
                .ok_or_else(||
                    map_timer_err!(TimerErrorType::EPoll(Errno::EINVAL), "timer poll has gone and not active!")
                )
                .map(|v| PollInterruptAq(v));
    }
}

/// A main instance which initializes the event listeners from the registered
/// timers.
#[repr(transparent)]
#[derive(Debug)]
pub struct TimerPoll(Arc<DefaultEventWatch>);

impl fmt::Display for TimerPoll
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        write!(f, "{}", self.0.as_ref())
    }
}

impl TimerPoll
{
    #[inline] 
    fn get_timer(&self) -> &DefaultEventWatch
    {
        return &self.0;
    }

    /// Creates new instance of the event listener.
    pub 
    fn new() -> TimerResult<Self>
    {
        return Ok( Self( Arc::new(DefaultEventWatch::new()?) ) );
    }

    /// Adds the timer to the event monitor. It accepts any reference to instance which
    /// implements [AsFd] and it is not limited specificly to timers. Maybe later this
    /// behaviour will me modified.
    /// 
    /// # Arguments
    /// 
    /// * `timer` - `T` where impl [AsTimerFd] a timer instance. The provided
    ///     FD will be polled for [EpollFlags::EPOLLIN] event types. 
    /// 
    /// # Returns
    /// 
    /// A [TimerResult] i.e [Result] is returned with error description in case of error.
    pub 
    fn add<T: AsTimerFd>(&self, timer: &T) -> TimerResult<()>
    {
        if timer.get_bind().is_some() == true
        {
            timer_err!(TimerErrorType::AlreadyPolled, "timer: '{}', already binded to polling instance: '{}'", timer, self);
        }

        self.get_timer().add(timer)?;

        let poll_inst = Arc::downgrade(&self.0);

        // bind timer
        timer.bind_poll(poll_inst);

        return Ok(());
    }

    /// Removes the specific timer's FD from the event monitor.
    /// 
    /// # Arguments
    /// 
    /// * `timer` - `T` where impl [AsTimerFd] a timer instance. 
    /// 
    /// # Returns
    /// 
    /// A [TimerResult] i.e [Result] is returned with error description in case of error.
    pub 
    fn delete<T: AsTimerFd>(&self, timer: &T) -> TimerResult<()>
    {
        let Some(binded_to) = timer.get_bind()
            else
            {
                timer_err!(TimerErrorType::NotFound, "timer: '{}', is not binded to polling instance: {}", timer, self);
            };
        
        // check if it belongs to this instance
        if binded_to != self.0
        {
            timer_err!(TimerErrorType::BelongOtherInstance, "timer: '{}', is not binded to this instance: {}", timer, self);
        }

        // unbind
        timer.unbind_poll();

        // remove from poll
        return self.get_timer().delete(timer);
    }

    /// Polls the event monitor for events. Depending on the `timeout` the behaviour will
    /// be different.
    /// 
    /// # Arguments
    /// 
    /// * `timeout` - poll timeout. If set to [Option::None] will block the current thread.
    ///     If set to [Option::Some] with inner value `0` will return immidiatly. The 
    ///     timeout is set in `miliseconds`.
    /// 
    /// # Returns 
    /// 
    /// A [TimerResult] i.e [Result] is returned with
    /// 
    /// * [Result::Ok] with the [Option] where:
    /// 
    ///     * [Option::Some] with the [Vec] with the [RawFd] of the timer's where the event has
    ///         happened.
    /// 
    ///     * [Option::None] if no events happened.
    /// 
    /// * [Result::Err] with error description.
    #[inline]
    pub  
    fn poll(&self, timeout: Option<i32>) -> TimerResult<PollResult>
    {
        return self.get_timer().poll(timeout);
    }

    #[inline]
    pub 
    fn get_poll_interruptor(&self) -> PollInterrupt
    {
        return self.get_timer().get_poll_interruptor();
    }

    #[inline]
    pub 
    fn interrupt_poll(&self) -> bool 
    {
        return self.get_timer().interrupt_poll();
    }
}

#[cfg(test)]
mod tests
{
    
    
    use std::sync::Arc;

    use crate::{timer_portable::{poll::{AsTimerFd, TimerPollOps}, timer::TimerFd, FdTimerCom, TimerFlags, TimerType}, TimerPoll};

    #[test]
    fn test_poll0()
    {
        let poll = TimerPoll::new().unwrap();

        let tm_fd0 = TimerFd::new("test0".into(), TimerType::CLOCK_REALTIME, TimerFlags::TFD_NONBLOCK).unwrap();

        poll.add(&tm_fd0).unwrap();

        assert_eq!(tm_fd0.get_bind().is_some(), true);
        
        // check dup
        let res = poll.add(&tm_fd0);
        assert_eq!(res.is_err(), true);
        println!("passed: {}", res.err().unwrap());

        // check timer drop
        drop(tm_fd0);

        assert_eq!(poll.get_timer().get_count(), 0);
        assert_eq!(Arc::weak_count(&poll.0), 0);
        println!("passed: weak count: {}, count: {}", Arc::weak_count(&poll.0), poll.get_timer().get_count());

        // check poll instance deinit
        let tm_fd0 = TimerFd::new("test0".into(), TimerType::CLOCK_REALTIME, TimerFlags::TFD_NONBLOCK).unwrap();
        poll.add(&tm_fd0).unwrap();

        assert_eq!(tm_fd0.get_bind().is_some(), true);

        drop(poll);

        let res = tm_fd0.get_bind();
        assert_eq!(res.is_none(), true);
        println!("passed: timer event watch is none;")
    }
}