timer_deque_rs/

lib.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
 */

//! # timer-deque-rs
//! 
//! Three deque types:
//! 
//! [TimerDequeueConsumer] consumes the item and places it on the queue.
//! ```ignore
//! let mut time_list = 
//!         OrderedTimerDeque
//!             ::<TimerDequeueConsumer<TestItem>>
//!             ::new("test_label".into(), 4, false).unwrap();
//! ```
//! 
//! 
//! [TimerDequeueSignalTicket] sends signal as specified in the callback(non-blocking) for every added item.
//! ```ignore
//! let mut time_list = 
//!         OrderedTimerDeque
//!             ::<TimerDequeueSignalTicket<TestSigStruct>>
//!             ::new("test_label".into(), 4, false).unwrap();
//! ```
//! 
//! 
//! [TimerDequeueTicketIssuer] issues a ticket which can be dropped (deallocated), so timer would ignore item.
//! ```ignore
//! let mut time_list = 
//!     OrderedTimerDeque
//!         ::<TimerDequeueTicketIssuer>
//!         ::new("test_label".into(), 4, false).unwrap();
//! ```
//! 
//! 
//! ## Timers polling
//! 
//! For the `sync` a `Epoll` for Linux and `Kqueue` for BSD are used. Both are
//! wrapped into [TimerPoll].
//! 
//! ```ignore
//! let ev_watch = TimerPoll::new().unwrap();
//! 
//! let mut time_list = 
//!     OrderedTimerDeque
//!         ::<TimerDequeueConsumer<Arc<TestItem>>>
//!         ::new("test_label".into(), 4, false).unwrap();
//! 
//!    // add timer to event 
//! ev_watch.add(&time_list).unwrap();
//! ```
//! In case if monitored timer, for example, `time_list` from above exmaple would be dropped intentionally or
//! by acident, it will be automatically removed from the poll queue. If, for any reason the `ev_watch` becomes
//! invalid i.e dropped, all added instances will be unbinded from this [TimerPoll] instance and can be reused.
//! 
//! Alternativly, [OrderedTimerDeque] provides blocking/nonblocking function
//! `wait_for_event` which is less efficient.
//! 
//! For the `async` a [Future] is implemented. Polling `future` is not too 
//! efficient (the same situation with `wait_for_event`).
//! 
//! ```ignore
//! let mut time_list = 
//!     OrderedTimerDeque
//!         ::<TimerDequeueConsumer<Arc<TestItem>>>
//!         ::new("test_label_async".into(), 4, false)
//!             .unwrap();
//! 
//! let res = time_list.poll().await.unwrap();
//! 
//! // ...
//! // read timeout items
//! time_list.timeout_event_handler(res, &mut timeout_items).unwrap();
//! ```
//! 
//! For more efficient `polling` of Timer for event, use async crates like
//! `smol`, `tokio` or other. In case of `tokio` an `AsyncFd can be used.`
//! 
//! ```ignore
//! let time_list = 
//!     OrderedTimerDeque
//!         ::<TimerDequeueSignalTicket<TestStruct>>
//!         ::new("test_label".into(), 4, false)
//!             .unwrap();
//! 
//! let mut async_time_list = AsyncFd::new(time_list).unwrap();
//! 
//! 
//! // poll the timer until it becomes ready
//! let mut read_guard = 
//!     async_time_list.ready_mut(Interest::READABLE).await.unwrap();
//! 
//! // clear ready otherwise it will return WOULDBLOCK
//! read_guard.clear_ready();
//! 
//! // read events
//! let res = read_guard.get_inner().wait_for_event().unwrap();
//! ```
//! 
//! ## Timer
//! 
//! A timer can be used directly.
//! 
//! ```ignore
//! // timer init as blocking
//! let timer = 
//!     TimerFd::new(Cow::Borrowed("test"), TimerType::CLOCK_REALTIME, TimerFlags::empty()).unwrap();
//! 
//! let now = chrono::offset::Local::now().timestamp();
//! let snow = now + 3;
//!    let s = Instant::now();
//!
//! // setting timer
//!    let res = 
//!        timer.set_time(TimerSetTimeFlags::TFD_TIMER_ABSTIME, TimerExpMode::OneShot{sec: snow, nsec: 0});
//! 
//! // read timer
//! let ovf = timer.read().unwrap().unwrap();
//! ```
//! 
//! The abobe is not too efficient because in case of `nonblocking`, it will return none immidiatly and
//! in case of `blocking` it would block thread.
//! 
//! A `Epoll`, `Select`, `KQueue` can be used to poll timer more efficient. Or, for example, `AsyncFd` from 
//! `tokio` can be used too. 
 
pub extern crate nix;
pub extern crate bitflags;
pub extern crate chrono;
pub extern crate rand;

/// All code which should be ported to the specific OS. Contains a system timer
/// implementation and poll.
pub mod timer_portable;

/// Crates error handling.
pub mod error;

/// Common things.
pub mod common;

/// 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.
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;

/// A `signal` sender. Calls the specified callback which must never block the executing thread.
pub mod timer_signal;

/// A base implementation of the sorted timer queue.
pub mod timer;

#[cfg(test)]
mod tests;

pub use timer::OrderedTimerDeque;

pub use timer_consumer::TimerDequeueConsumer;
pub use timer_signal::{TimerDequeueSignal, TimerDequeueSignalTicket};
pub use timer_tickets::{TimerDequeueTicketIssuer, TimerDequeueTicket, TimerDequeueId};

pub use timer_portable::{TimerPoll, TimerReadRes, FdTimerCom};