timer-deque-rs 0.8.0

/*-
 * 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. The MIT License (MIT)
 *                     
 *   3. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

/// A `consumer` type of the timer which consumes the intance and returns it when
/// timer triggers. The `consumed` instance normally whould be [Send] because it will
/// be moved into the timer which may be processed in other thread.
pub mod timer_consumer;

/// A `ticket` issuer. Issues a ticket which should be assigned to the instance whcih was added
/// to the timer's queue. The `ticket` can be used to remove the item from queue before the 
/// timeout event. If ticket is dropped i.e connection closed, the ticket will be
/// in timer's queue until timeout where it will be ignored on timeout event.
pub mod timer_tickets;

#[cfg(test)]
mod tests;

#[cfg(target_family = "unix")]
pub use std::os::fd::{AsFd, AsRawFd, BorrowedFd, RawFd};

use std::
{
    borrow::Cow, 
    collections::VecDeque, 
    fmt, 
    marker::PhantomData, 
};


use crate::
{
    TimerDequeConsumer, 
    TimerDequeTicket, 
    TimerDequeTicketIssuer, 
    error::{TimerErrorType, TimerResult}, 
    map_timer_err, 
    timer_err, 
    timer_portable::
    {
        AsTimerId, FdTimerMarker, PollEventType, TimerFd, TimerFlags, TimerId, TimerType, UnixFd, portable_error::TimerPortResult, timer::
        {
            AbsoluteTime, FdTimerCom, FdTimerRead, RelativeTime, TimerExpMode, 
            TimerReadRes
        }
    }
};


/// A trait which is implemented by the structs which define the operation mode of the deque.
/// 
/// At the moment for: [DequeOnce] and [DequePeriodic].
pub trait OrderedTimerDequeMode: fmt::Debug + fmt::Display + Ord + PartialOrd + Eq + PartialEq
{
    /// A type of operation. If the item deques once, then this value should be
    /// `true`. Otherwise, it is periodic.
    const IS_ONCE: bool;

    /// Checks the current instance against the provided `cmp` [AbsoluteTime].
    /// It is expected that the current instance's timeout value is actual and 
    /// haven't outlive the `cmp` already. if it does the error:
    /// [TimerErrorType::Expired] should be returned. Or any other error
    /// if it is required.
    fn validate_time(&self, cmp: AbsoluteTime) -> TimerResult<()>;
    
    /// Returns the `absolute` timeout for the instance of the deque.
    fn get_absolut_timeout(&self) -> AbsoluteTime;

    /// Postpones the time by the relative offset `post_time`. May return error
    /// (if required) if the absolut timeout value overflows.
    /// 
    /// May return [TimerErrorType::TicketInstanceGone] if ticket was invalidated.
    fn postpone(&mut self, posp_time: RelativeTime) -> TimerResult<()>;

    /// Updates the timeout when the deque works in periodic mode. By fedault
    /// it does nothing.
    fn advance_timeout(&mut self)
    {
        return;
    }
}

/// This queue mode removes all entries from the queue that have timed out.
/// 
/// The further behaviour is defined by the type of the deque.
#[derive(Debug, Clone, Copy)]
pub struct DequeOnce 
{
    /// A timeout for the item in the queue.
    absolute_timeout: AbsoluteTime,
}

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

impl Ord for DequeOnce
{
    fn cmp(&self, other: &Self) -> std::cmp::Ordering 
    {
        return self.absolute_timeout.cmp(&other.absolute_timeout);
    }
}

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

impl Eq for DequeOnce {}

impl PartialEq for DequeOnce
{
    fn eq(&self, other: &Self) -> bool 
    {
        return self.absolute_timeout == other.absolute_timeout;
    }
}


impl OrderedTimerDequeMode for DequeOnce
{
    const IS_ONCE: bool = true;

    fn get_absolut_timeout(&self) -> AbsoluteTime
    {
        return self.absolute_timeout;
    }
    
    fn validate_time(&self, cmp: AbsoluteTime) -> TimerResult<()> 
    {
        if cmp > self.absolute_timeout
        {
            timer_err!(TimerErrorType::Expired, 
                "deque once time already expired, now: {}, req: {}", cmp, self);
        }

        return Ok(());
    }
    
    fn postpone(&mut self, posp_time: RelativeTime) -> TimerResult<()> 
    {
        self.absolute_timeout = self.absolute_timeout + posp_time;

        return Ok(());
    }
}


impl DequeOnce
{
    /// Creates new instacne.
    #[inline]
    pub
    fn new(absolute_timeout: impl Into<AbsoluteTime>) -> Self
    {
        return Self{ absolute_timeout: absolute_timeout.into() };
    }
}

/// This queue mode does not remove an element that has timed out (by `absolute_timeout`), 
/// but extends (by `relative_period`) the timeout and returns the element back to the queue.
#[derive(Debug, Clone, Copy)]
pub struct DequePeriodic 
{
    /// Extends the timer until the next timeout. This is `relative`
    /// not absolute.
    relative_period: RelativeTime,

    /// A timeout value.
    absolute_timeout: AbsoluteTime,
}

impl fmt::Display for DequePeriodic
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        write!(f, "{}, rel: {}", self.absolute_timeout, self.relative_period)
    }
}

impl Ord for DequePeriodic
{
    fn cmp(&self, other: &Self) -> std::cmp::Ordering 
    {
        return self.absolute_timeout.cmp(&other.absolute_timeout);
    }
}

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

impl Eq for DequePeriodic {}

impl PartialEq for DequePeriodic
{
    fn eq(&self, other: &Self) -> bool 
    {
        return self.absolute_timeout == other.absolute_timeout;
    }
}


impl OrderedTimerDequeMode for DequePeriodic
{
    const IS_ONCE: bool = false;

    fn get_absolut_timeout(&self) -> AbsoluteTime
    {
        return self.absolute_timeout;
    }

    fn advance_timeout(&mut self)
    {
        self.absolute_timeout += self.relative_period;
    }

    fn validate_time(&self, cmp: AbsoluteTime) -> TimerResult<()> 
    {
        if cmp > self.absolute_timeout
        {
            timer_err!(TimerErrorType::Expired, 
                "deque periodic absolute time already expired, now: {}, req: {}", cmp, self.absolute_timeout);
        }
        else if self.relative_period.is_zero() == false
        {
            timer_err!(TimerErrorType::ZeroRelativeTime, 
                "deque periodic relative time is 0, rel_time: {}", self.relative_period);
        }

        return Ok(());
    }
    
    fn postpone(&mut self, posp_time: RelativeTime) -> TimerResult<()> 
    {
        self.absolute_timeout = self.absolute_timeout - self.relative_period + posp_time;

        self.relative_period = posp_time;

        return Ok(());
    }
}

impl DequePeriodic
{
    /// Creates new instance. The `relative_time` is not added to
    /// `absolute_time` until timeout. The values are unchecked at this
    /// point and will be checked during placement in queue.
    pub
    fn new_from_now(rel_time: impl Into<RelativeTime>) -> Self
    {
        let inst = 
            Self
            {
                relative_period:
                    rel_time.into(),
                absolute_timeout: 
                    AbsoluteTime::now(),
            };

        return inst;
    }

    /// Creates new instance with the initial timeout `abs_time` and
    /// period `rel_time` which is added to the `abs_time` each time
    /// the timeout occures. The values are unchecked at this
    /// point and will be checked during placement in queue.
    pub
    fn new(abs_time: impl Into<AbsoluteTime>, rel_time: impl Into<RelativeTime>) -> Self
    {
        let inst = 
            Self
            {
                relative_period:
                    rel_time.into(),
                absolute_timeout: 
                    abs_time.into(),
            };

        return inst;
    }
}

/// A trait for the generalization of the collection type which is used to 
/// collect the timeout values i.e ticket IDs.
pub trait TimerTimeoutCollection<ITEM: PartialEq + Eq + fmt::Display + fmt::Debug>
{
    /// Initializes the instance.
    fn new() -> Self;

    /// Store the `ITEM` in the collection.
    fn push(&mut self, item: ITEM);

    /// Wraps the instance into [Option]. If collection is `empty` a
    /// [Option::None] should be returned.
    fn into_option(self) -> Option<Self> where Self: Sized;
}

/// An implementation for the Vec.
impl<ITEM: PartialEq + Eq + fmt::Display + fmt::Debug> TimerTimeoutCollection<ITEM> 
for Vec<ITEM>
{
    fn new() -> Self
    {
        return Vec::new();
    }

    fn push(&mut self, item: ITEM) 
    {
        self.push(item);
    }

    fn into_option(self) -> Option<Self>
    {
        if self.is_empty() == false
        {
            return Some(self);
        }
        else
        {
            return None;
        }
    }
}

/// A dummy implementation when nothing is returned. Unused at the moment.
impl <ITEM: PartialEq + Eq + fmt::Display + fmt::Debug> TimerTimeoutCollection<ITEM> 
for ()
{
    fn new() -> Self
    {
        return ();
    }

    fn push(&mut self, _item: ITEM) 
    {
        return;    
    }

    fn into_option(self) -> Option<Self>
    {
        return None;
    }
}

/// A standart interface for each deque type. Every deque type must implement this 
/// trait.
pub trait OrderedTimerDequeHandle<MODE: OrderedTimerDequeMode>
    : Ord + PartialOrd + PartialEq + PartialEq<Self::TimerId> + Eq + fmt::Debug + 
        fmt::Display + OrderedTimerDequeInterf<MODE>
{
    /// A timer ID. Normally this is a uniq identificator of the item in the queue. 
    /// i.e `TimerDequeId`.
    type TimerId: PartialEq + Eq + fmt::Display + fmt::Debug;

    /// A collection which is used to collect the items which are removed from
    /// the queue due to timeout.
    type HandleRes: TimerTimeoutCollection<Self::TimerId>;

    /// Postpones the timeout of the current instance. The `postp_time` is a [RelativeTime] 
    /// i.e inroduces the offset.
    fn postpone(&mut self, postp_time: RelativeTime) -> TimerResult<()>;

    /// Reschedules the current instance. This is different from the `postpone` as the
    /// instance is assagned with a new time. The `MODE` cannot be changed, only time.
    fn resched(&mut self, time: MODE) -> TimerResult<()>;

    /// A spefic code which is called during timeout routine handling. Normally is should 
    /// store the result into the `collection` and reschedule the item if it is repeated.
    fn handle(self, timer_self: &mut OrderTimerDeque<MODE, Self>, 
        timer_ids: &mut Self::HandleRes) -> TimerResult<()>
    where Self: Sized;

    /// Matches the current instance with provided `other` instances 
    /// [OrderedTimerDequeHandle::TimerId]. But, the `PartialEq<Self::TimerId>` is 
    /// implemented, so the `==` can be used to compare.
    fn is_same(&self, other: &Self::TimerId) -> bool;

    /// Attempts to acquire the [OrderedTimerDequeHandle::TimerId] by consuming the instance.
    fn into_timer_id(self) -> Option<Self::TimerId>;
}

/// A trait which is used by the base [OrderTimerDeque]. 
/// This is an interface which provides access to the timeout value of the instance.
pub trait OrderedTimerDequeInterf<MODE: OrderedTimerDequeMode>
{
    /// Returns the absolute time and the timer mode.
    fn get_timeout_absolute(&self) -> AbsoluteTime;
}


/// A [VecDeque] based queue which is sorted (in ascending order) by the timeout 
/// which is `absolute` time.
/// 
/// The queue automatically manages the `timer` i.e setting, unsetting.
/// 
/// Also for each type of the deque, a event procesing function is providided.
/// 
/// There are two types of queue:
/// 
/// * [OrderdTimerDequeOnce] - after timeout the element is removed from the queue.
/// 
/// * [OrderdTimerDequePeriodic] - after timeout the element timeout is extended
///     until the item is not removed from the queue manually.
/// 
/// And there are 3 types of queue models:
/// 
/// * [`crate::TimerDequeConsumer`] - consumes the item which is stored in the 
///     timeout queue.
/// 
/// * [`crate::TimerDequeTicketIssuer`] - issues a ticket which is referenced 
///     to the item in the queue.
/// 
/// * [`crate::TimerDequeSignalTicket`] - send signal on timeout using `MPSC`
/// 
/// # Implementations
/// 
/// If `feature = enable_mio_compat` is enabled a [mio::event::Source] is 
/// implemented on the current struct.
/// 
/// ## Multithread
/// 
/// Not MT-safe. The external mutex should be used to protect the instance. 
/// The internal `timer` [TimerFd] is MT-safe.
/// 
/// ## Poll
/// 
/// - A built-in [crate::TimerPoll] can be used.
/// 
/// - An external crate MIO [crate::TimerFdMioCompat] if `feature = enable_mio_compat` is
/// enabled.
/// 
/// - User implemented poll. The FD can be aquired via [AsRawFd] [AsFd].
/// 
/// ## Async
/// 
/// A [Future] is implemented.
/// # Generics
/// 
/// * `DQI` - a deque type. There are three types are available:
///     * - [crate::TimerDequeueTicketIssuer] issues a ticket for the instance for which the timer was set.
///     ```ignore
///         let mut time_list = 
///             OrderedTimerDeque
///                 ::<TimerDequeTicketIssuer<OrderdTimerDequeOnce>>
///                 ::new("test_label".into(), 4, false).unwrap();
///     ```  
///     or
///     ```ignore
///         let mut time_list = 
///             OrderedTimerDeque
///                 ::<TimerDequeTicketIssuer<OrderdTimerDequePeriodic>>
///                 ::new("test_label".into(), 4, false).unwrap();
///     ```     
///     * - [crate::TimerDequeueConsumer] consumes the instance for which the timer is set.
///     ```ignore
///         let mut time_list = 
///             OrderedTimerDeque
///                 ::<TimerDequeConsumer<TestItem, OrderdTimerDequeOnce>>
///                 ::new("test_label".into(), 4, false).unwrap();
///     ```  
///     or
///     ```ignore
///         let mut time_list = 
///             OrderedTimerDeque
///                 ::<TimerDequeConsumer<TestItem, OrderdTimerDequePeriodic>>
///                 ::new("test_label".into(), 4, false).unwrap();
///     ``` 
///     * - [crate::TimerDequeueSignalTicket] sends a signal to destination.
///     ```ignore
///         let mut time_list = 
///             OrderedTimerDeque
///                 ::<TimerDequeSignalTicket<TestSigStruct, OrderdTimerDequeOnce>>
///                 ::new("test_label".into(), 4, false).unwrap();
///     ```
///     or
///     ```ignore
///         let mut time_list = 
///             OrderedTimerDeque
///                 ::<TimerDequeSignalTicket<TestSigStruct, OrderdTimerDequePeriodic>>
///                 ::new("test_label".into(), 4, false).unwrap();
///     ```
#[derive(Debug, Eq)]
pub struct OrderTimerDeque<MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>>
{
    /// A [VecDeque] list which is sorted by time in ascending order -
    /// lower first, largest last
    pub(crate) deque_timeout_list: VecDeque<INTF>,

    /// An instance of the FFI (Kernel Supported Timer)
    pub(crate) timer: TimerFd,

    p: PhantomData<MODE>
}

#[cfg(all(target_family = "unix", feature = "enable_mio_compat"))]
pub mod mio_compat
{
    use std::{io, os::fd::{AsRawFd, RawFd}};

    use mio::{Token, unix::SourceFd};

    use crate::{TimerFdMioCompat, deque_timeout::{OrderTimerDeque, OrderedTimerDequeHandle, OrderedTimerDequeMode}};

    impl<MODE, INTF> mio::event::Source for OrderTimerDeque<MODE, INTF>
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn register(
            &mut self,
            registry: &mio::Registry,
            token: mio::Token,
            interests: mio::Interest,
        ) -> io::Result<()> 
        {
            return 
                SourceFd(&self.as_raw_fd()).register(registry, token, interests);
        }

        fn reregister(
            &mut self,
            registry: &mio::Registry,
            token: mio::Token,
            interests: mio::Interest,
        ) -> io::Result<()> 
        {
            return 
                SourceFd(&self.as_raw_fd()).reregister(registry, token, interests);
        }

        fn deregister(&mut self, registry: &mio::Registry) -> io::Result<()> 
        {
            return 
                SourceFd(&self.as_raw_fd()).deregister(registry)
        }
    }

    impl<MODE, INTF> PartialEq<Token> for OrderTimerDeque<MODE, INTF>
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn eq(&self, other: &Token) -> bool 
        {
            return self.as_raw_fd() == other.0 as RawFd;
        }
    }

    impl<MODE, INTF> TimerFdMioCompat for OrderTimerDeque<MODE, INTF>
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn get_token(&self) -> Token
        {
            return Token(self.as_raw_fd() as usize);
        }
    }
}

impl<MODE, INTF> UnixFd for OrderTimerDeque<MODE, INTF> 
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{

}

impl<MODE, INTF> AsTimerId for OrderTimerDeque<MODE, INTF> 
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    fn as_timer_id(&self) -> TimerId 
    {
        return self.timer.as_timer_id();
    }
}

impl<MODE, INTF> FdTimerRead for OrderTimerDeque<MODE, INTF> 
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    fn read(&self) -> TimerPortResult<TimerReadRes<u64>> 
    {
        return self.timer.read();
    }
}

impl<MODE, INTF> PartialEq<str> for OrderTimerDeque<MODE, INTF> 
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    fn eq(&self, other: &str) -> bool 
    {
        return self.timer.as_ref() == other;
    }
}


impl<MODE, INTF> FdTimerMarker for OrderTimerDeque<MODE, INTF> 
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    fn clone_timer(&self) -> TimerFd 
    {
        return self.timer.clone_timer();
    }

    fn get_strong_count(&self) -> usize 
    {
        return self.timer.get_strong_count();
    }
}

impl<MODE, INTF> Drop for OrderTimerDeque<MODE, INTF> 
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    fn drop(&mut self) 
    {
        let _ = self.clean_up_timer();
    }
}

impl<MODE, INTF> AsRef<str> for OrderTimerDeque<MODE, INTF>
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    fn as_ref(&self) -> &str 
    {
        return self.timer.as_ref();
    }
}

#[cfg(target_family = "unix")]
pub mod deque_timeout_os
{
    use super::*;

    impl<MODE, INTF> AsFd for OrderTimerDeque<MODE, INTF> 
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn as_fd(&self) -> BorrowedFd<'_> 
        {
            return self.timer.as_fd();
        }
    }

    impl<MODE, INTF> AsRawFd for OrderTimerDeque<MODE, INTF> 
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn as_raw_fd(&self) -> RawFd 
        {
            return self.timer.as_raw_fd();
        }
    }

    impl<MODE, INTF> PartialEq<RawFd> for OrderTimerDeque<MODE, INTF> 
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn eq(&self, other: &RawFd) -> bool 
        {
            return self.timer == *other;
        }
    }
}

#[cfg(target_family = "windows")]
pub mod deque_timeout_os
{
    use std::os::windows::io::{AsHandle, AsRawHandle, BorrowedHandle, RawHandle};

    use super::*;
    
    impl<MODE, INTF> AsHandle for OrderTimerDeque<MODE, INTF> 
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn as_handle(&self) -> BorrowedHandle<'_> 
        {
            return self.timer.as_handle();
        }
    }

    impl<MODE, INTF> AsRawHandle for OrderTimerDeque<MODE, INTF> 
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn as_raw_handle(&self) -> RawHandle 
        {
            return self.timer.as_raw_handle();
        }
    }

    impl<MODE, INTF> PartialEq<RawHandle> for OrderTimerDeque<MODE, INTF> 
    where 
        MODE: OrderedTimerDequeMode, 
        INTF: OrderedTimerDequeHandle<MODE>
    {
        fn eq(&self, other: &RawHandle) -> bool 
        {
            return self.timer == *other;
        }
}
}

impl<MODE, INTF> fmt::Display for OrderTimerDeque<MODE, INTF> 
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        write!(f, "timer: '{}', fd: '{}', queue_len: '{}'", 
            self.timer, self.timer.as_timer_id(), self.deque_timeout_list.len())
    }
}

impl<MODE, INTF> PartialEq for OrderTimerDeque<MODE, INTF> 
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    fn eq(&self, other: &Self) -> bool 
    {
        return self.timer == other.timer;
    }
}



impl<MODE, R> OrderTimerDeque<MODE, TimerDequeConsumer<R, MODE>> 
where 
    MODE: OrderedTimerDequeMode,
    R: PartialEq + Eq + fmt::Debug + fmt::Display + Send + Clone
{
    /// Adds the new absolute timeout to the timer deque instance.
    /// 
    /// The `entity` is an item which should be stored in the deque
    /// amd on timeout - returned.
    /// 
    /// # Generics
    /// 
    /// * `MODE` - is any type which implements the [OrderedTimerDequeMode].
    ///   There are two options: [DequeOnce] and [DequePeriodic].
    /// 
    /// # Arguemnts
    /// 
    /// * `item` - `R` which is an item to store in the deque.
    /// 
    /// * `mode` - `MODE` a timeout value which also defines the
    ///  behaviour of the deque logic. 
    /// 
    /// # Returns
    /// 
    /// A [Result] as alias [TimerResult] is returned with:
    /// 
    /// * [Result::Ok] with the [common::NoTicket] ticket which is dummy value.
    /// 
    /// * [Result::Err] with error description.
    /// 
    /// Possible errors: 
    ///     
    /// * [TimerErrorType::Expired] - `mode` contains time which have alrealy expired.
    /// 
    /// * [TimerErrorType::ZeroRelativeTime] - `mode` [DequePeriodic] relative time 
    ///     should never be zero.
    /// 
    /// * [TimerErrorType::TimerError] - a error with the OS timer. Contains subcode
    ///     `errno`.
    pub 
    fn add(&mut self, item: R, mode: MODE) -> TimerResult<()>
    {
        let inst = 
            TimerDequeConsumer::<R, MODE>::new(item, mode)?;

        //return self.queue_item(inst)
        let res = self.queue_item(inst);
        return res;
    }
}


impl<MODE> OrderTimerDeque<MODE, TimerDequeTicketIssuer<MODE>> 
where 
    MODE: OrderedTimerDequeMode
{
    /// Adds the new absolute timeout to the timer deque instance.
    /// 
    /// This deque assigns the `ticket` for each timeout which is
    /// used for identification and invalidation.
    /// 
    /// # Generics
    /// 
    /// * `MODE` - is any type which implements the [OrderedTimerDequeMode].
    ///   There are two options: [DequeOnce] and [DequePeriodic].
    /// 
    /// # Arguemnts
    /// 
    /// * `mode` - `MODE` a timeout value which also defines the
    ///  behaviour of the deque logic. 
    /// 
    /// # Returns
    /// 
    /// A [Result] as alias [TimerResult] is returned with:
    /// 
    /// * [Result::Ok] with the [common::NoTicket] ticket which is dummy value.
    /// 
    /// * [Result::Err] with error description.
    /// 
    /// Possible errors: 
    ///     
    /// * [TimerErrorType::Expired] - `mode` contains time which have alrealy expired.
    /// 
    /// * [TimerErrorType::ZeroRelativeTime] - `mode` [DequePeriodic] relative time 
    ///     should never be zero.
    /// 
    /// * [TimerErrorType::TimerError] - a error with the OS timer. Contains subcode
    ///     `errno`.
    pub 
    fn add(&mut self, mode: MODE) -> TimerResult<TimerDequeTicket>
    {
        let (inst, ticket) = 
            TimerDequeTicketIssuer::<MODE>::new(mode)?;

        self.queue_item(inst)?;

        return Ok(ticket);
    }
}

impl<MODE, INTF> OrderTimerDeque<MODE, INTF>  
where 
    MODE: OrderedTimerDequeMode, 
    INTF: OrderedTimerDequeHandle<MODE>
{
    /// Creates new deque instance with the provided parameters.
    /// 
    /// # Argument
    /// 
    /// * `timer_label` - a label which helps to identify the timer.
    /// 
    /// * `deq_len` - a minimal, pre-allocated deque length.
    /// 
    /// * `cloexec` - when set to `true` sets the `CLOEXEC` flag on FD.
    /// 
    /// * `non_blocking` - when set to `true` sets the `TFD_NONBLOCK` flag on FD.
    /// 
    /// # Returns
    /// 
    /// A [Result] as alias [TimerResult] is returned with
    /// 
    /// * [Result::Ok] with the instance.
    /// 
    /// * [Result::Err] with the error description.
    /// 
    /// The following errors may be returned:
    ///     
    /// * [TimerErrorType::TimerError] - error in the OS timer. A `errno` subcode is provided.
    pub 
    fn new(timer_label: Cow<'static, str>, deq_len: usize, cloexec: bool, non_blocking: bool) -> TimerResult<OrderTimerDeque<MODE, INTF>>
    {
        let deq_len = 
            if deq_len == 0
            {
                10
            }
            else
            {
                deq_len
            };

        let mut tf = TimerFlags::empty();

        tf.set(TimerFlags::TFD_CLOEXEC, cloexec);
        tf.set(TimerFlags::TFD_NONBLOCK, non_blocking);

        // init timer
        let timer = 
            TimerFd::new(timer_label, TimerType::CLOCK_REALTIME, tf)
                .map_err(|e|
                    map_timer_err!(TimerErrorType::TimerError(e.get_errno()), "{}", e)
                )?;

        return Ok( 
            Self
            { 
                deque_timeout_list: VecDeque::with_capacity(deq_len), 
                timer: timer,
                p: PhantomData,
            } 
        );
    }

    /// internal function which is called from the `add()` functions.
    pub(super)  
    fn queue_item(&mut self, inst: INTF) -> TimerResult<()>
    {
        if self.deque_timeout_list.len() == 0
        {
            let timer_stamp = 
                TimerExpMode::<AbsoluteTime>::new_oneshot(inst.get_timeout_absolute());

            // setup timer
            self
                .timer
                .get_timer()
                .set_time(timer_stamp)
                .map_err(|e|
                    map_timer_err!(TimerErrorType::TimerError(e.get_errno()), "{}", e)
                )?;

            self.deque_timeout_list.push_front(inst);      
        }
        else
        {
            // list can not be empty from this point
            let front_timeout = 
                self.deque_timeout_list.front().unwrap().get_timeout_absolute();

            // intances timeout
            let inst_timeout = inst.get_timeout_absolute();

            if front_timeout >= inst_timeout
            {
                // push to front
                self.deque_timeout_list.push_front(inst);

                self.reschedule_timer()?;
            }
            else 
            {
                let back_banuntil = 
                    self
                        .deque_timeout_list
                        .back()
                        .unwrap()
                        .get_timeout_absolute();

                if back_banuntil <= inst_timeout
                {
                    // push to the back
                    self.deque_timeout_list.push_back(inst);
                }
                else
                {
                    let pos = 
                        self
                            .deque_timeout_list
                            .binary_search_by( |se| 
                                se.get_timeout_absolute().cmp(&inst.get_timeout_absolute())
                            )
                            .map_or_else(|e| e, |r| r);

                    self.deque_timeout_list.insert(pos, inst);
                }
            }
        }

        return Ok(());
    }

    /// Removes the instance from the queue by the identification depending on the
    /// deque type.
    /// 
    /// # Arguments
    /// 
    /// `item` - identification of the item which should be removed from the queue.
    /// 
    /// # Returns
    /// 
    /// A [Result] as alias [TimerResult] is returned with:
    /// 
    /// * [Result::Ok] with the inner type [Option] where
    ///     * [Option::Some] is returned with the consumed `item`.
    ///     * [Option::None] is returned when item was not found.
    /// 
    /// * [Result::Err] with error description.
    /// 
    /// The following errors may be returned:
    ///     
    /// * [TimerErrorType::TimerError] - error in the OS timer. A `errno` subcode is provided.
    pub 
    fn remove_from_queue(&mut self, item: &INTF::TimerId) -> TimerResult<Option<INTF::TimerId>>
    {
        return 
            self
                .remove_from_queue_int(item)
                .map(|opt_intf|
                    {
                        let Some(intf) = opt_intf
                        else { return None };

                        return intf.into_timer_id();
                    }
                );
                
    }
    
    pub(super)  
    fn remove_from_queue_int(&mut self, item: &INTF::TimerId) -> TimerResult<Option<INTF>>
    {
        if self.deque_timeout_list.len() == 0
        {
            timer_err!(TimerErrorType::QueueEmpty, "queue list is empty!");
        }
        else
        {
            // search for the item in list
            if self.deque_timeout_list.len() == 1
            {
                // just pop the from the front
                let ret_ent = self.deque_timeout_list.pop_front().unwrap();

                if &ret_ent != item
                {
                    self.deque_timeout_list.push_front(ret_ent);

                    return Ok(None);
                }

                // stop timer
                self.stop_timer()?;

                return Ok(Some(ret_ent));
            }
            else
            {
                // in theory the `ticket` is a reference to ARC, so the weak should be upgraded 
                // succesfully for temoved instance.

                for (pos, q_item) 
                in self.deque_timeout_list.iter().enumerate()
                {
                    if q_item == item
                    {
                        // remove by the index
                        let ret_ent = 
                            self.deque_timeout_list.remove(pos).unwrap();

                        // call timer reset if index is 0 (front)
                        if pos == 0 
                        {
                            self.reschedule_timer()?;
                        }

                        return Ok(Some(ret_ent));
                    }
                }

                return Ok(None);
            }
        }
    }

    /// Reads the timer's FD to retrive the event type and then calling 
    /// the event handler. Then the result is returned. The result may 
    /// contain the `items` which were removed from the queue or copied.
    /// 
    /// This function behaves differently when the timer is initialized as
    /// a `non-blocking` i.e with [TimerFlags::TFD_NONBLOCK].
    /// 
    /// When [TimerFlags::TFD_NONBLOCK] is not set, this function will block reading the FD.
    /// In case of 'EINTR', the read attempt will be repeated. 
    /// 
    /// When [TimerFlags::TFD_NONBLOCK] is set, the function will return with some result 
    /// immidiatly.
    /// 
    /// # Return
    /// 
    /// * In case of `EAGAIN`, the [TimerReadRes::WouldBlock] will be returned. 
    /// 
    /// * In case of `ECANCELLD`, the [TimerReadRes::Cancelled] will be returned.
    /// 
    /// * In case of any other error the [Result::Err] is returned.
    /// 
    /// When a timer fires an event the [Result::Ok] is returned with the amount of
    /// timer overrun. Normally it is 1.
    pub 
    fn wait_for_event_and_process(&mut self) -> TimerResult<Option<INTF::HandleRes>>
    {
        let res = 
            self
                .timer
                .read()
                .map_err(|e|
                    map_timer_err!(TimerErrorType::TimerError(e.get_errno()), "{}", e)
                )?;


        // ignore wouldblock
        if let TimerReadRes::WouldBlock = res
        {
            return Ok(None);
        }

        return Ok(self.internal_handle_timer_event()?);
    }

    /// Handles the single event received from the `poll` and
    /// returns the result. The result may 
    /// contain the `items` which were removed from the queue or copied.  
    /// 
    /// # Arguments
    /// 
    /// `pet` - [PollEventType] an event from the timer to handle.
    /// 
    /// A [Result] as alias [TimerResult] is returned with:
    /// 
    /// * [Result::Ok] witout any innder data.
    /// 
    /// * [Result::Err] with error description.
    pub 
    fn handle_timer_event(&mut self, pet: PollEventType) -> TimerResult<Option<INTF::HandleRes>>
    {
        match pet
        {
            PollEventType::TimerRes(_, res) => 
            {
                // ignore wouldblock
                if let TimerReadRes::WouldBlock = res
                {
                    return Ok(None);
                }

                return self.internal_handle_timer_event();
            },
            PollEventType::SubError(_, err) => 
            {
                timer_err!(TimerErrorType::TimerError(err.get_errno()), "{}", err)
            }
        }
        
    }

    fn internal_handle_timer_event(&mut self) -> TimerResult<Option<INTF::HandleRes>>
    {
        let cur_timestamp = AbsoluteTime::now();
        let mut timer_ids: INTF::HandleRes = INTF::HandleRes::new();

        loop 
        {
            // get from front of the queue
            let Some(front_entity) = self.deque_timeout_list.front() 
                else { break };

            let time_until = front_entity.get_timeout_absolute();

            if time_until <= cur_timestamp
            {
                let deq = self.deque_timeout_list.pop_front().unwrap();

                deq.handle(self, &mut timer_ids)?;
            }
            else
            {
                break;
            }
        }

        // call timer reschedule
        self.reschedule_timer()?;

        return Ok(timer_ids.into_option());
    }

    /// Asynchronious polling. The timer's FD is set to nonblocking,
    /// so each time it will return `pending` and load CPU. If you are using
    /// `tokio` or `smol` or other crate, the corresponding helpers like 
    /// tokio's `AsyncFd` can be used to wrap the instance. The timer is read-only
    /// so use `read-only interest` to avoid errors.
    /// 
    /// If [TimerReadRes::WouldBlock] is received then returns immidiatly.
    pub async
    fn async_poll_for_event_and_process(&mut self) -> TimerResult<Option<INTF::HandleRes>>
    {
        let res =  
            self
                .timer
                .get_timer()
                .await
                .map_err(|e|
                    map_timer_err!(TimerErrorType::TimerError(e.get_errno()), "{}", e)
                )?;

        // ignore wouldblock
        if let TimerReadRes::WouldBlock = res
        {
            return Ok(None);
        }

        return Ok(self.internal_handle_timer_event()?);
    }

    /// Returns the queue length.
    pub 
    fn timer_queue_len(&self) -> usize
    {
        return self.deque_timeout_list.len();
    }
    
    /// Postpones the instace `target` by the relative time `rel_time_off`.
    /// 
    /// # Errors
    /// 
    /// * [TimerErrorType::NotFound] - if instance `target` was not found.
    /// 
    /// * [TimerErrorType::TicketInstanceGone] - if ticket was invalidated.
    /// 
    /// * [TimerErrorType::TimerError] - with the suberror code.
    pub 
    fn postpone(&mut self, target: &INTF::TimerId, rel_time_off: RelativeTime) -> TimerResult<()>
    {
        let mut item = 
            self
                .remove_from_queue_int(target)?
                .ok_or(map_timer_err!(TimerErrorType::NotFound, "ticket: {} not found", target))?;

        
        item.postpone(rel_time_off)?;

        self.queue_item(item)?;

        return Ok(()); 
    }

    /// Reschedules the instace `target` by assigning new time `time` 
    /// which is of type `MODE`.
    /// 
    /// # Errors
    /// 
    /// * [TimerErrorType::NotFound] - if instance `target` was not found.
    /// 
    /// * [TimerErrorType::TicketInstanceGone] - if ticket was invalidated.
    /// 
    /// * [TimerErrorType::TimerError] - with the suberror code.
    /// 
    /// * [TimerErrorType::Expired] - if provided `time` have passed.
    pub 
    fn reschedule(&mut self, target: &INTF::TimerId, time: MODE) -> TimerResult<()>
    {
        let mut item = 
            self.remove_from_queue_int(target)?
                .ok_or(map_timer_err!(TimerErrorType::NotFound, "{} not found", target))?;

        
        item.resched(time)?;

        self.queue_item(item)?;

        return Ok(()); 
    }

    /// Starts the `timer` instance by setting timeout or stops the `timer` if the
    /// instnce's `queue` is empty.
    pub(super)   
    fn reschedule_timer(&mut self) -> TimerResult<()>
    {
        if let Some(front_entity) = self.deque_timeout_list.front()
        {
            let timer_exp = 
                TimerExpMode::<AbsoluteTime>::new_oneshot(front_entity.get_timeout_absolute());

            return
                self
                    .timer
                    .get_timer()
                    .set_time(timer_exp)
                    .map_err(|e|
                        map_timer_err!(TimerErrorType::TimerError(e.get_errno()), "{}", e)
                    );
        }
        else
        {
            // queue is empty, force timer to stop

            return 
                self
                    .timer
                    .get_timer()
                    .unset_time()
                    .map_err(|e|
                        map_timer_err!(TimerErrorType::TimerError(e.get_errno()), "{}", e)
                    );
        }
    }

    /// Unarms timer and clears the queue.
    pub 
    fn clean_up_timer(&mut self) -> TimerResult<()>
    {
        self
            .timer
            .get_timer()
            .unset_time()
            .map_err(|e| map_timer_err!(TimerErrorType::TimerError(e.get_errno()), "{}", e))?;

        self.deque_timeout_list.clear();

        return Ok(());
    }

    /// Unarms timer only.
    pub 
    fn stop_timer(&mut self) -> TimerResult<()>
    {
        return 
            self
                .timer
                .get_timer()
                .unset_time()
                .map_err(|e| map_timer_err!(TimerErrorType::TimerError(e.get_errno()), "{}", e));
    }

}