zrx_store/queue/
item.rs

1// Copyright (c) 2025-2026 Zensical and contributors
2
3// SPDX-License-Identifier: MIT
4// All contributions are certified under the DCO
5
6// Permission is hereby granted, free of charge, to any person obtaining a copy
7// of this software and associated documentation files (the "Software"), to
8// deal in the Software without restriction, including without limitation the
9// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10// sell copies of the Software, and to permit persons to whom the Software is
11// furnished to do so, subject to the following conditions:
12
13// The above copyright notice and this permission notice shall be included in
14// all copies or substantial portions of the Software.
15
16// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
19// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22// IN THE SOFTWARE.
23
24// ----------------------------------------------------------------------------
25
26//! Queue item.
27
28use std::cmp::Ordering;
29use std::time::Instant;
30
31// ----------------------------------------------------------------------------
32// Structs
33// ----------------------------------------------------------------------------
34
35/// Queue item.
36///
37/// Items are stored in queues, and can have arbitrary associated data. An item
38/// has a specific deadline, which is the ordering property of the queue.
39///
40/// Items must only be considered for processing when their deadline has passed,
41/// which is exactly what [`Queue::take`][] ensures. This allows to implement
42/// timers and intervals in an efficient manner. In case two items have the
43/// same deadline, order is undefined, but this doesn't matter for us.
44///
45/// Note that mutable data needs to be stored outside of the queue, as items are
46/// immutable. The built-in [`Queue`][] uses a [`Slab`][] for this matter.
47///
48/// [`Queue`]: crate::queue::Queue
49/// [`Queue::take`]: crate::queue::Queue::take
50/// [`Slab`]: slab::Slab
51#[derive(Clone, Debug)]
52pub struct Item<T = usize> {
53    /// Deadline.
54    deadline: Instant,
55    /// Associated data.
56    data: T,
57}
58
59// ----------------------------------------------------------------------------
60// Implementations
61// ----------------------------------------------------------------------------
62
63impl<T> Item<T> {
64    /// Creates a queue item.
65    ///
66    /// # Examples
67    ///
68    /// ```
69    /// use zrx_store::queue::Item;
70    ///
71    /// // Create queue item
72    /// let item = Item::new(42);
73    /// ```
74    #[must_use]
75    pub fn new(data: T) -> Self {
76        Self { deadline: Instant::now(), data }
77    }
78
79    /// Updates the deadline of the queue item.
80    ///
81    /// # Examples
82    ///
83    /// ```
84    /// use std::time::Instant;
85    /// use zrx_store::queue::Item;
86    ///
87    /// // Create queue item and set deadline
88    /// let mut item = Item::new(42);
89    /// item.set_deadline(Instant::now());
90    /// ```
91    #[inline]
92    pub fn set_deadline(&mut self, deadline: Instant) {
93        self.deadline = deadline;
94    }
95}
96
97// ----------------------------------------------------------------------------
98
99impl<T> Item<T> {
100    /// Returns the deadline.
101    #[inline]
102    pub fn deadline(&self) -> Instant {
103        self.deadline
104    }
105
106    /// Returns a reference to the associated data.
107    #[inline]
108    pub fn data(&self) -> &T {
109        &self.data
110    }
111}
112
113// ----------------------------------------------------------------------------
114// Trait implementations
115// ----------------------------------------------------------------------------
116
117impl<T> PartialEq for Item<T>
118where
119    T: PartialEq,
120{
121    /// Compares two queue items for equality.
122    ///
123    /// Note that two queue items are considered being equal if their associated
124    /// data is equal. Deadlines are solely relevant for ordering.
125    ///
126    /// # Examples
127    ///
128    /// ```
129    /// use zrx_store::queue::Item;
130    ///
131    /// // Create and compare queue items
132    /// let a = Item::new(42);
133    /// let b = Item::new(42);
134    /// assert_eq!(a, b);
135    /// ```
136    fn eq(&self, other: &Self) -> bool {
137        self.data == other.data
138    }
139}
140
141impl<T> Eq for Item<T> where T: Eq {}
142
143// ----------------------------------------------------------------------------
144
145impl<T> PartialOrd for Item<T>
146where
147    T: Eq,
148{
149    /// Orders two queue items.
150    ///
151    /// # Examples
152    ///
153    /// ```
154    /// use zrx_store::queue::Item;
155    ///
156    /// // Create and compare queue items
157    /// let a = Item::new(42);
158    /// let b = Item::new(84);
159    /// assert!(a <= b);
160    /// ```
161    #[inline]
162    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
163        Some(self.cmp(other))
164    }
165}
166
167impl<T> Ord for Item<T>
168where
169    T: Eq,
170{
171    /// Orders two queue items.
172    ///
173    /// # Examples
174    ///
175    /// ```
176    /// use zrx_store::queue::Item;
177    ///
178    /// // Create and compare queue items
179    /// let a = Item::new(42);
180    /// let b = Item::new(84);
181    /// assert!(a <= b);
182    /// ```
183    fn cmp(&self, other: &Self) -> Ordering {
184        self.deadline.cmp(&other.deadline)
185    }
186}
zrx_store/queue/item.rs

zrx_store/queue/
item.rs
