zrx_store/queue/
iter.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//! Iterator implementations for [`Queue`].
27
28use slab::Slab;
29use std::ptr;
30use std::time::Instant;
31
32use crate::store::decorator::ordered;
33use crate::store::item::{Key, Value};
34use crate::store::{
35    StoreIterable, StoreIterableMut, StoreKeys, StoreMut, StoreValues,
36};
37
38use super::item::Item;
39use super::Queue;
40
41// ----------------------------------------------------------------------------
42// Structs
43// ----------------------------------------------------------------------------
44
45/// Iterator over the items of a [`Queue`].
46#[derive(Debug)]
47pub struct Iter<'a, K, V>
48where
49    K: Key,
50{
51    /// Inner iterator.
52    inner: ordered::Iter<'a, K, Item>,
53    /// Queue items.
54    items: &'a Slab<V>,
55    /// Cutoff deadline.
56    deadline: Instant,
57}
58
59/// Mutable iterator over the items of a [`Queue`].
60pub struct IterMut<'a, K, V>
61where
62    K: Key,
63{
64    /// Inner iterator.
65    inner: ordered::Iter<'a, K, Item>,
66    /// Queue items.
67    items: &'a mut Slab<V>,
68    /// Cutoff deadline.
69    deadline: Instant,
70}
71
72/// Iterator over the keys of a [`Queue`].
73pub struct Keys<'a, K>
74where
75    K: Key,
76{
77    /// Inner iterator.
78    inner: ordered::Iter<'a, K, Item>,
79    /// Cutoff deadline.
80    deadline: Instant,
81}
82
83/// Iterator over the values of a [`Queue`].
84pub struct Values<'a, K, V>
85where
86    K: Key,
87{
88    /// Inner iterator.
89    inner: ordered::Values<'a, K, Item>,
90    /// Queue items.
91    items: &'a Slab<V>,
92    /// Cutoff deadline.
93    deadline: Instant,
94}
95
96// ----------------------------------------------------------------------------
97// Trait implementations
98// ----------------------------------------------------------------------------
99
100impl<K, V, S> StoreIterable<K, V> for Queue<K, V, S>
101where
102    K: Key,
103    V: Value,
104    S: StoreIterable<K, Item>,
105{
106    type Iter<'a> = Iter<'a, K, V>
107    where
108        Self: 'a;
109
110    /// Creates an iterator over the items of the queue.
111    ///
112    /// # Examples
113    ///
114    /// ```
115    /// use zrx_store::{Queue, StoreIterable, StoreMut};
116    ///
117    /// // Create queue and initial state
118    /// let mut queue = Queue::default();
119    /// queue.insert("key", 42);
120    ///
121    /// // Create iterator over the queue
122    /// for (key, value) in queue.iter() {
123    ///     println!("{key}: {value}");
124    /// }
125    /// ```
126    #[inline]
127    fn iter(&self) -> Self::Iter<'_> {
128        Iter {
129            inner: self.store.iter(),
130            items: &self.items,
131            deadline: Instant::now(),
132        }
133    }
134}
135
136impl<K, V, S> StoreIterableMut<K, V> for Queue<K, V, S>
137where
138    K: Key,
139    V: Value,
140    S: StoreMut<K, Item> + StoreIterable<K, Item>,
141{
142    type IterMut<'a> = IterMut<'a, K, V>
143    where
144        Self: 'a;
145
146    /// Creates a mutable iterator over the items of the queue.
147    ///
148    /// # Examples
149    ///
150    /// ```
151    /// use zrx_store::{Queue, StoreIterableMut, StoreMut};
152    ///
153    /// // Create queue and initial state
154    /// let mut queue = Queue::default();
155    /// queue.insert("key", 42);
156    ///
157    /// // Create iterator over the queue
158    /// for (key, value) in queue.iter_mut() {
159    ///     println!("{key}: {value}");
160    /// }
161    /// ```
162    #[inline]
163    fn iter_mut(&mut self) -> Self::IterMut<'_> {
164        IterMut {
165            inner: self.store.iter(),
166            items: &mut self.items,
167            deadline: Instant::now(),
168        }
169    }
170}
171
172impl<K, V, S> StoreKeys<K, V> for Queue<K, V, S>
173where
174    K: Key,
175    S: StoreIterable<K, Item>,
176{
177    type Keys<'a> = Keys<'a, K>
178    where
179        Self: 'a;
180
181    /// Creates an iterator over the keys of the queue.
182    ///
183    /// # Examples
184    ///
185    /// ```
186    /// use zrx_store::{Queue, StoreKeys, StoreMut};
187    ///
188    /// // Create queue and initial state
189    /// let mut queue = Queue::default();
190    /// queue.insert("key", 42);
191    ///
192    /// // Create iterator over the queue
193    /// for key in queue.keys() {
194    ///     println!("{key}");
195    /// }
196    /// ```
197    #[inline]
198    fn keys(&self) -> Self::Keys<'_> {
199        Keys {
200            inner: self.store.iter(),
201            deadline: Instant::now(),
202        }
203    }
204}
205
206impl<K, V, S> StoreValues<K, V> for Queue<K, V, S>
207where
208    K: Key,
209    V: Value,
210    S: StoreValues<K, Item>,
211{
212    type Values<'a> = Values<'a, K, V>
213    where
214        Self: 'a;
215
216    /// Creates an iterator over the values of the queue.
217    ///
218    /// # Examples
219    ///
220    /// ```
221    /// use zrx_store::{Queue, StoreMut, StoreValues};
222    ///
223    /// // Create queue and initial state
224    /// let mut queue = Queue::default();
225    /// queue.insert("key", 42);
226    ///
227    /// // Create iterator over the queue
228    /// for value in queue.values() {
229    ///     println!("{value}");
230    /// }
231    /// ```
232    #[inline]
233    fn values(&self) -> Self::Values<'_> {
234        Values {
235            inner: self.store.values(),
236            items: &self.items,
237            deadline: Instant::now(),
238        }
239    }
240}
241
242// ----------------------------------------------------------------------------
243
244impl<'a, K, V> Iterator for Iter<'a, K, V>
245where
246    K: Key,
247{
248    type Item = (&'a K, &'a V);
249
250    /// Returns the next item.
251    #[inline]
252    fn next(&mut self) -> Option<Self::Item> {
253        self.inner.find_map(|(key, item)| {
254            (item.deadline() <= self.deadline)
255                .then(|| (key, &self.items[*item.data()]))
256        })
257    }
258
259    /// Returns the bounds on the remaining length of the iterator.
260    #[inline]
261    fn size_hint(&self) -> (usize, Option<usize>) {
262        self.inner.size_hint()
263    }
264}
265
266// ----------------------------------------------------------------------------
267
268impl<'a, K, V> Iterator for IterMut<'a, K, V>
269where
270    K: Key,
271{
272    type Item = (&'a K, &'a mut V);
273
274    /// Returns the next item.
275    #[inline]
276    fn next(&mut self) -> Option<Self::Item> {
277        // Obtain a mutable pointer to the queue items, as we need to reference
278        // it in the closure passed to the iterator's map method
279        let items = ptr::addr_of_mut!(*self.items);
280        self.inner.find_map(|(key, item)| {
281            (item.deadline() <= self.deadline)
282                // SAFETY: The borrow checker won't let us return a mutable
283                // reference to an item in the slab, but we know this is safe,
284                // as the store and the slab are two distinct data structures
285                // that are synchronized with each other
286                .then(|| (key, unsafe { &mut (&mut *items)[*item.data()] }))
287        })
288    }
289
290    /// Returns the bounds on the remaining length of the iterator.
291    #[inline]
292    fn size_hint(&self) -> (usize, Option<usize>) {
293        self.inner.size_hint()
294    }
295}
296
297// ----------------------------------------------------------------------------
298
299impl<'a, K> Iterator for Keys<'a, K>
300where
301    K: Key,
302{
303    type Item = &'a K;
304
305    /// Returns the next item.
306    #[inline]
307    fn next(&mut self) -> Option<Self::Item> {
308        self.inner.find_map(|(key, item)| {
309            (item.deadline() <= self.deadline).then_some(key)
310        })
311    }
312
313    /// Returns the bounds on the remaining length of the iterator.
314    #[inline]
315    fn size_hint(&self) -> (usize, Option<usize>) {
316        self.inner.size_hint()
317    }
318}
319
320// ----------------------------------------------------------------------------
321
322impl<'a, K, V> Iterator for Values<'a, K, V>
323where
324    K: Key,
325{
326    type Item = &'a V;
327
328    /// Returns the next item.
329    #[inline]
330    fn next(&mut self) -> Option<Self::Item> {
331        self.inner.find_map(|item| {
332            (item.deadline() <= self.deadline)
333                .then(|| &self.items[*item.data()])
334        })
335    }
336
337    /// Returns the bounds on the remaining length of the iterator.
338    #[inline]
339    fn size_hint(&self) -> (usize, Option<usize>) {
340        self.inner.size_hint()
341    }
342}
zrx_store/queue/iter.rs

zrx_store/queue/
iter.rs
