Skip to main content

mytheclipse_queue/
in_memory.rs

1//! In-process job queue: a topic map guarded by an `RwLock` plus one
2//! `Mutex<Vec<Job>>` + `Notify` per topic.
3//!
4//! Both locks are synchronous. Neither is ever held across an `.await`, so
5//! there is nothing for an async mutex to buy here — and a `std` mutex avoids
6//! the waker-list bookkeeping an async one pays on every acquisition. Topic
7//! lookup takes the map's read lock, so producers and consumers on the same
8//! topic do not serialize on a global lock.
9
10use std::collections::HashMap;
11use std::sync::{Arc, Mutex, RwLock};
12use std::time::Duration;
13
14use async_trait::async_trait;
15use tokio::sync::Notify;
16
17use crate::error::{JobError, QueueError};
18use crate::job::{Job, JobId};
19use crate::traits::Queue;
20
21struct TopicQueue {
22    /// Jobs waiting to be delivered. Never locked across an `.await`.
23    jobs: Mutex<Vec<Job>>,
24    notify: Notify,
25}
26
27impl TopicQueue {
28    fn new() -> Self {
29        Self {
30            jobs: Mutex::new(Vec::new()),
31            notify: Notify::new(),
32        }
33    }
34
35    /// Pushes `job` and wakes one waiting consumer.
36    fn push(&self, job: Job) {
37        self.jobs.lock().expect("job queue poisoned").push(job);
38        self.notify.notify_one();
39    }
40}
41
42impl std::fmt::Debug for TopicQueue {
43    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
44        f.debug_struct("TopicQueue")
45            .field(
46                "jobs_len",
47                &self.jobs.try_lock().map(|j| j.len()).unwrap_or(0),
48            )
49            .finish()
50    }
51}
52
53/// An in-memory queue. Each topic is a shared mutex-protected vector + Notify.
54#[derive(Clone)]
55pub struct InMemoryQueue {
56    topics: Arc<RwLock<HashMap<String, Arc<TopicQueue>>>>,
57}
58
59impl std::fmt::Debug for InMemoryQueue {
60    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
61        f.debug_struct("InMemoryQueue").finish()
62    }
63}
64
65impl Default for InMemoryQueue {
66    fn default() -> Self {
67        Self::new()
68    }
69}
70
71impl InMemoryQueue {
72    /// Creates an empty queue with no topics.
73    pub fn new() -> Self {
74        Self {
75            topics: Arc::new(RwLock::new(HashMap::new())),
76        }
77    }
78
79    /// The queue for `topic`, created on first use. Existing topics are served
80    /// from the read lock and without allocating a key.
81    fn topic(&self, topic: &str) -> Arc<TopicQueue> {
82        let existing = self.topics.read().unwrap().get(topic).cloned();
83        if let Some(tq) = existing {
84            return tq;
85        }
86        let mut topics = self.topics.write().unwrap();
87        Arc::clone(
88            topics
89                .entry(topic.to_owned())
90                .or_insert_with(|| Arc::new(TopicQueue::new())),
91        )
92    }
93}
94
95#[async_trait]
96impl Queue for InMemoryQueue {
97    async fn enqueue(&self, topic: &str, payload: Vec<u8>) -> Result<(), QueueError> {
98        let job = Job::new(JobId::generate(), topic, payload);
99        self.topic(topic).push(job);
100        Ok(())
101    }
102
103    async fn dequeue(&self, topic: &str, timeout: Duration) -> Result<Option<Job>, QueueError> {
104        let tq = self.topic(topic);
105        let deadline = tokio::time::Instant::now() + timeout;
106        loop {
107            if let Some(job) = tq.jobs.lock().expect("job queue poisoned").pop() {
108                return Ok(Some(job));
109            }
110            // One deadline for the whole call, so a spurious wake-up does not
111            // restart the wait.
112            tokio::select! {
113                _ = tq.notify.notified() => {}
114                _ = tokio::time::sleep_until(deadline) => {
115                    return Ok(tq.jobs.lock().expect("job queue poisoned").pop());
116                }
117            }
118        }
119    }
120
121    async fn ack(&self, _job: &Job) -> Result<(), JobError> {
122        // Dequeue already removed the job, so there is nothing left to
123        // acknowledge; the in-flight copy is the handler's own.
124        Ok(())
125    }
126
127    async fn nack(&self, job: &Job, requeue: bool) -> Result<(), JobError> {
128        if requeue {
129            let tq = self.topic(&job.topic);
130            // Requeue the *same* job (same id) with its attempt count advanced:
131            // a fresh `Job::new` would reset the counter and make the worker's
132            // retry budget unenforceable (endless redelivery, never a DLQ).
133            let retried = Job {
134                attempt: job.attempt + 1,
135                delivered_at: Some(std::time::SystemTime::now()),
136                ..job.clone()
137            };
138            tq.push(retried);
139        }
140        Ok(())
141    }
142
143    async fn dlq_move(&self, topic: &str, job: Job) -> Result<(), QueueError> {
144        let dlq_topic = format!("dlq:{topic}");
145        self.topic(&dlq_topic).push(job);
146        Ok(())
147    }
148
149    async fn len(&self, topic: &str) -> Result<u64, QueueError> {
150        let tq = self.topic(topic);
151        let guard = tq.jobs.lock().expect("job queue poisoned");
152        Ok(guard.len() as u64)
153    }
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159
160    #[tokio::test]
161    async fn enqueue_dequeue_roundtrip() {
162        let q = InMemoryQueue::new();
163        q.enqueue("test", b"hello".to_vec()).await.unwrap();
164        let job = q
165            .dequeue("test", Duration::from_millis(500))
166            .await
167            .unwrap()
168            .unwrap();
169        assert_eq!(job.payload, b"hello");
170        assert_eq!(job.topic, "test");
171    }
172
173    #[tokio::test]
174    async fn empty_returns_none() {
175        let q = InMemoryQueue::new();
176        let result = q.dequeue("none", Duration::from_millis(50)).await.unwrap();
177        assert!(result.is_none());
178    }
179
180    #[tokio::test]
181    async fn len_tracks_jobs() {
182        let q = InMemoryQueue::new();
183        q.enqueue("t", vec![1]).await.unwrap();
184        q.enqueue("t", vec![2]).await.unwrap();
185        assert_eq!(q.len("t").await.unwrap(), 2);
186    }
187
188    #[tokio::test]
189    async fn requeue_advances_attempt_on_the_same_job() {
190        let q = InMemoryQueue::new();
191        q.enqueue("t", vec![1]).await.unwrap();
192        let job = q
193            .dequeue("t", Duration::from_millis(50))
194            .await
195            .unwrap()
196            .unwrap();
197        assert_eq!(job.attempt, 0);
198
199        q.nack(&job, true).await.unwrap();
200        let again = q
201            .dequeue("t", Duration::from_millis(50))
202            .await
203            .unwrap()
204            .unwrap();
205        assert_eq!(again.id, job.id, "retry must keep the job identity");
206        assert_eq!(again.attempt, 1, "retry must advance the attempt counter");
207    }
208}