timer_deque_rs/

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

//! # timer-deque-rs
//! 
//! ## A crate which combines a timer with the different deque types.
//! 
//! <img src="https://cdn.4neko.org/timer_deque_rs.webp" width="280"/> <img src="https://cdn.4neko.org/source_avail.webp" width="280"/> <img src="https://cdn.4neko.org/mpl_or_eupl_500.webp" width="280"/>
//! 
//! ## Timer dequeue 
//! 
//! A deque which uses timer to deque objects.
//! 
//! ### Two deque opeartion modes:
//! 
//! * [OrderdTimerDequeOnce] - after a timeout an item is removed from the queue.
//! 
//! * [OrderdTimerDequePeriodic] - after the timeout an item's timeout is extended 
//!     and item is returned back to queue. It should be manually removed.
//! 
//! ## Features
//! 
//! ### Below is related to BSD systems
//! - `bsd_use_timerfd` - use `timerfd` instead of `kqueue`
//! - `bsd_use_poll` - use `poll` instread of `kqueue`
//! 
//! ### Three deque types:
//! 
//! [TimerDequeueConsumer] consumes the item and places it on the queue.
//! ```ignore
//! let mut time_list = 
//!         OrderedTimerDeque
//!             ::<TimerDequeueConsumer<TestItem, OrderdTimerDequeOnce>>
//!             ::new("test_label".into(), 4, false).unwrap();
//! ```
//! or
//! ```ignore
//! let mut time_list = 
//!         OrderedTimerDeque
//!             ::<TimerDequeueConsumer<TestItem, OrderdTimerDequePeriodic>>
//!             ::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, OrderdTimerDequeOnce>>
//!             ::new("test_label".into(), 4, false).unwrap();
//! ```
//! or
//! ```ignore
//! let mut time_list = 
//!         OrderedTimerDeque
//!             ::<TimerDequeueSignalTicket<TestSigStruct, OrderdTimerDequePeriodic>>
//!             ::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<OrderdTimerDequeOnce>>
//!         ::new("test_label".into(), 4, false).unwrap();
//! ```
//! or
//! ```ignore
//! let mut time_list = 
//!     OrderedTimerDeque
//!         ::<TimerDequeueTicketIssuer<OrderdTimerDequePeriodic>>
//!         ::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>, OrderdTimerDequeOnce>>
//!         ::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>, OrderdTimerDequeOnce>>
//!         ::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>, OrderdTimerDequeOnce>
//!         ::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();
//! 
//! // setting the timout and timer mode
//! let abs_time = AbsoluteTime::now().add_sec(3);
//! 
//! // the flags will be set automatically
//! let exp_time = 
//!     TimerExpMode::<AbsoluteTime>::new_oneshot(abs_time);
//!
//! // setting timer
//!    let res = 
//!        timer.set_time(exp_time);
//! 
//! // read timer
//! let ovf = timer.read().unwrap().unwrap();
//! ```
//! 
//! The above 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. 
//! 
//! ## Task spawn and executer
//! 
//! A parallel task execution based on the task timeout.
//! 
//! ```ignore
//! 
//! #[derive(Debug)]
//! struct TaskStruct1
//! {
//!     a1: u64,
//!     s: Sender<u64>,
//! }
//! 
//! impl TaskStruct1
//! {
//!     fn new(a1: u64, s: Sender<u64>) -> Self
//!     {
//!         return Self{ a1: a1, s };
//!     }
//! }
//! 
//! impl PeriodicTask for TaskStruct1
//! {
//!     fn exec(&mut self) -> PeriodicTaskResult
//!     {
//!         println!("taskstruct1 val: {}", self.a1);
//! 
//!         let _ = self.s.send(self.a1);
//! 
//!         return PeriodicTaskResult::Ok;
//!     }
//! }
//! 
//! // ...
//! 
//! let s = SyncPeriodicTasks::new(2.try_into().unwrap()).unwrap();
//! 
//! // ...
//! 
//! let task1 = TaskStruct1::new(0, send.clone());
//!    let task1_ptt = 
//!         PeriodicTaskTime::interval(RelativeTime::new_time(1, 0));
//! 
//! let task5 = TaskStruct1::new(4, send.clone());
//!    let task5_ptt = 
//!         PeriodicTaskTime::exact_time(AbsoluteTime::now() + RelativeTime::new_time(5, 0));
//! 
//! let task1_guard = s.add("task1", task1, task1_ptt).unwrap();
//! let task5_guard = s.add("task5", task5, task5_ptt).unwrap();
//! 
//! // ...
//! ```
//! 
 
pub extern crate nix;
pub extern crate bitflags;
pub extern crate chrono;
pub extern crate rand;
pub extern crate crossbeam_deque;


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

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

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

pub mod periodic_task;

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

//pub mod shared_state;

//pub mod periodic_timeout;

#[cfg(test)]
mod tests;

// deque
pub use deque_timeout::{OrderedTimerDeque, OrderdTimerDequeOnce, OrderdTimerDequePeriodic};

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

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

pub use common::TimerDequeueId;

pub use periodic_task::{PeriodicTask, PeriodicTaskResult, SyncPeriodicTasks, PeriodicTaskTime};