Struct OrderTimerDeque 

pub struct OrderTimerDeque<MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>> { /* private fields */ }

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.

      let mut time_list = 
          OrderedTimerDeque
              ::<TimerDequeTicketIssuer<OrderdTimerDequeOnce>>
              ::new("test_label".into(), 4, false).unwrap();

  or

      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.

      let mut time_list = 
          OrderedTimerDeque
              ::<TimerDequeConsumer<TestItem, OrderdTimerDequeOnce>>
              ::new("test_label".into(), 4, false).unwrap();

  or

      let mut time_list = 
          OrderedTimerDeque
              ::<TimerDequeConsumer<TestItem, OrderdTimerDequePeriodic>>
              ::new("test_label".into(), 4, false).unwrap();

  • • [crate::TimerDequeueSignalTicket] sends a signal to destination.

      let mut time_list = 
          OrderedTimerDeque
              ::<TimerDequeSignalTicket<TestSigStruct, OrderdTimerDequeOnce>>
              ::new("test_label".into(), 4, false).unwrap();

  or

      let mut time_list = 
          OrderedTimerDeque
              ::<TimerDequeSignalTicket<TestSigStruct, OrderdTimerDequePeriodic>>
              ::new("test_label".into(), 4, false).unwrap();

Implementations

impl<MODE, R> OrderTimerDeque<MODE, TimerDequeConsumer<R, MODE>>

where MODE: OrderedTimerDequeMode, R: PartialEq + Eq + Debug + Display + Send + Clone,

pub fn add(&mut self, item: R, mode: MODE) -> TimerResult<()>

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.

impl<MODE> OrderTimerDeque<MODE, TimerDequeTicketIssuer<MODE>>

where MODE: OrderedTimerDequeMode,

pub fn add(&mut self, mode: MODE) -> TimerResult<TimerDequeTicket>

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.

impl<MODE, INTF> OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

pub fn new( timer_label: Cow<'static, str>, deq_len: usize, cloexec: bool, non_blocking: bool, ) -> TimerResult<OrderTimerDeque<MODE, INTF>>

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 remove_from_queue( &mut self, item: &INTF::TimerId, ) -> TimerResult<Option<INTF::TimerId>>

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 wait_for_event_and_process( &mut self, ) -> TimerResult<Option<INTF::HandleRes>>

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 handle_timer_event( &mut self, pet: PollEventType, ) -> TimerResult<Option<INTF::HandleRes>>

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 async fn async_poll_for_event_and_process( &mut self, ) -> TimerResult<Option<INTF::HandleRes>>

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 fn timer_queue_len(&self) -> usize

Returns the queue length.

pub fn postpone( &mut self, target: &INTF::TimerId, rel_time_off: RelativeTime, ) -> TimerResult<()>

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 reschedule( &mut self, target: &INTF::TimerId, time: MODE, ) -> TimerResult<()>

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 clean_up_timer(&mut self) -> TimerResult<()>

Unarms timer and clears the queue.

pub fn stop_timer(&mut self) -> TimerResult<()>

Unarms timer only.

Trait Implementations

impl<MODE, INTF> AsFd for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl<MODE, INTF> AsRawFd for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl<MODE, INTF> AsRef<str> for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl<MODE, INTF> AsTimerId for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn as_timer_id(&self) -> TimerId

Returns the uniq timer ID number.

impl<MODE: Debug + OrderedTimerDequeMode, INTF: Debug + OrderedTimerDequeHandle<MODE>> Debug for OrderTimerDeque<MODE, INTF>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<MODE, INTF> Display for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<MODE, INTF> Drop for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn drop(&mut self)

Executes the destructor for this type.

impl<MODE, INTF> FdTimerMarker for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn clone_timer(&self) -> TimerFd

Clones the instance of the timer.

fn get_strong_count(&self) -> usize

Returns the count of strong references to inner type.

impl<MODE, INTF> FdTimerRead for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn read(&self) -> TimerPortResult<TimerReadRes<u64>>

Attempts to read the timer. The realization is different on different OS. The main purpose is to check if timer is ready (ended).

impl<MODE, INTF> PartialEq<i32> for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn eq(&self, other: &RawFd) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<MODE, INTF> PartialEq<str> for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<MODE, INTF> PartialEq for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<MODE: Eq + OrderedTimerDequeMode, INTF: Eq + OrderedTimerDequeHandle<MODE>> Eq for OrderTimerDeque<MODE, INTF>

impl<MODE, INTF> UnixFd for OrderTimerDeque<MODE, INTF>

where MODE: OrderedTimerDequeMode, INTF: OrderedTimerDequeHandle<MODE>,