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    pub fn new() -> Self {
73        Self {
74            topics: Arc::new(RwLock::new(HashMap::new())),
75        }
76    }
77
78    /// The queue for `topic`, created on first use. Existing topics are served
79    /// from the read lock and without allocating a key.
80    fn topic(&self, topic: &str) -> Arc<TopicQueue> {
81        let existing = self.topics.read().unwrap().get(topic).cloned();
82        if let Some(tq) = existing {
83            return tq;
84        }
85        let mut topics = self.topics.write().unwrap();
86        Arc::clone(
87            topics
88                .entry(topic.to_owned())
89                .or_insert_with(|| Arc::new(TopicQueue::new())),
90        )
91    }
92}
93
94#[async_trait]
95impl Queue for InMemoryQueue {
96    async fn enqueue(&self, topic: &str, payload: Vec<u8>) -> Result<(), QueueError> {
97        let job = Job::new(JobId::generate(), topic, payload);
98        self.topic(topic).push(job);
99        Ok(())
100    }
101
102    async fn dequeue(&self, topic: &str, timeout: Duration) -> Result<Option<Job>, QueueError> {
103        let tq = self.topic(topic);
104        let deadline = tokio::time::Instant::now() + timeout;
105        loop {
106            if let Some(job) = tq.jobs.lock().expect("job queue poisoned").pop() {
107                return Ok(Some(job));
108            }
109            // One deadline for the whole call, so a spurious wake-up does not
110            // restart the wait.
111            tokio::select! {
112                _ = tq.notify.notified() => {}
113                _ = tokio::time::sleep_until(deadline) => {
114                    return Ok(tq.jobs.lock().expect("job queue poisoned").pop());
115                }
116            }
117        }
118    }
119
120    async fn ack(&self, _job: &Job) -> Result<(), JobError> {
121        // Dequeue already removed the job, so there is nothing left to
122        // acknowledge; the in-flight copy is the handler's own.
123        Ok(())
124    }
125
126    async fn nack(&self, job: &Job, requeue: bool) -> Result<(), JobError> {
127        if requeue {
128            let tq = self.topic(&job.topic);
129            // Requeue the *same* job (same id) with its attempt count advanced:
130            // a fresh `Job::new` would reset the counter and make the worker's
131            // retry budget unenforceable (endless redelivery, never a DLQ).
132            let retried = Job {
133                attempt: job.attempt + 1,
134                delivered_at: Some(std::time::SystemTime::now()),
135                ..job.clone()
136            };
137            tq.push(retried);
138        }
139        Ok(())
140    }
141
142    async fn dlq_move(&self, topic: &str, job: Job) -> Result<(), QueueError> {
143        let dlq_topic = format!("dlq:{topic}");
144        self.topic(&dlq_topic).push(job);
145        Ok(())
146    }
147
148    async fn len(&self, topic: &str) -> Result<u64, QueueError> {
149        let tq = self.topic(topic);
150        let guard = tq.jobs.lock().expect("job queue poisoned");
151        Ok(guard.len() as u64)
152    }
153}
154
155#[cfg(test)]
156mod tests {
157    use super::*;
158
159    #[tokio::test]
160    async fn enqueue_dequeue_roundtrip() {
161        let q = InMemoryQueue::new();
162        q.enqueue("test", b"hello".to_vec()).await.unwrap();
163        let job = q
164            .dequeue("test", Duration::from_millis(500))
165            .await
166            .unwrap()
167            .unwrap();
168        assert_eq!(job.payload, b"hello");
169        assert_eq!(job.topic, "test");
170    }
171
172    #[tokio::test]
173    async fn empty_returns_none() {
174        let q = InMemoryQueue::new();
175        let result = q.dequeue("none", Duration::from_millis(50)).await.unwrap();
176        assert!(result.is_none());
177    }
178
179    #[tokio::test]
180    async fn len_tracks_jobs() {
181        let q = InMemoryQueue::new();
182        q.enqueue("t", vec![1]).await.unwrap();
183        q.enqueue("t", vec![2]).await.unwrap();
184        assert_eq!(q.len("t").await.unwrap(), 2);
185    }
186
187    #[tokio::test]
188    async fn requeue_advances_attempt_on_the_same_job() {
189        let q = InMemoryQueue::new();
190        q.enqueue("t", vec![1]).await.unwrap();
191        let job = q
192            .dequeue("t", Duration::from_millis(50))
193            .await
194            .unwrap()
195            .unwrap();
196        assert_eq!(job.attempt, 0);
197
198        q.nack(&job, true).await.unwrap();
199        let again = q
200            .dequeue("t", Duration::from_millis(50))
201            .await
202            .unwrap()
203            .unwrap();
204        assert_eq!(again.id, job.id, "retry must keep the job identity");
205        assert_eq!(again.attempt, 1, "retry must advance the attempt counter");
206    }
207}