Skip to main content

mytheclipse_queue/
backpressure_enqueue.rs

1//! Backpressure-aware enqueuer (in-memory backend).
2//!
3//! [`BackpressureEnforcer`] tracks un-acked jobs per topic and caps how many may
4//! be outstanding at once, returning [`BackpressureError`] instead of blocking
5//! when the cap is exceeded.
6
7use std::collections::HashMap;
8use std::sync::atomic::{AtomicU64, Ordering};
9use std::sync::{Arc, Mutex};
10
11use crate::error::QueueError;
12use crate::traits::Queue;
13
14/// Errors returned by [`BackpressureEnforcer`].
15#[derive(Debug)]
16pub enum BackpressureError {
17    /// The configured per-topic cap was reached; enqueue rejected.
18    LimitReached {
19        /// The topic whose cap was reached.
20        topic: String,
21    },
22    /// The underlying queue rejected the enqueue.
23    Enqueue(QueueError),
24}
25
26impl std::fmt::Display for BackpressureError {
27    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
28        match self {
29            Self::LimitReached { topic } => {
30                write!(f, "backpressure: in-flight limit reached for topic {topic}")
31            }
32            Self::Enqueue(e) => write!(f, "backpressure: enqueue failed: {e}"),
33        }
34    }
35}
36
37impl std::error::Error for BackpressureError {
38    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
39        match self {
40            Self::LimitReached { .. } => None,
41            Self::Enqueue(e) => Some(e),
42        }
43    }
44}
45
46/// Caps how many un-acked jobs a topic may have outstanding.
47///
48/// A slot is taken by [`try_enqueue`](Self::try_enqueue) and returned by
49/// [`dec_finished`](Self::dec_finished), so the cap holds only if the caller
50/// pairs them. Nothing here releases a slot on its own: the enforcer cannot know
51/// when a handler finished.
52pub struct BackpressureEnforcer {
53    /// Maximum un-acked jobs allowed per topic.
54    max_per_topic: u64,
55    /// Per-topic slot counter.
56    counters: Mutex<HashMap<String, Arc<AtomicU64>>>,
57}
58
59impl BackpressureEnforcer {
60    /// Creates an enforcer that allows `max_inflight` un-acked jobs per topic.
61    ///
62    /// A cap of zero would reject every enqueue, so it is clamped to one.
63    pub fn new(max_inflight: usize) -> Self {
64        Self {
65            max_per_topic: max_inflight.max(1) as u64,
66            counters: Mutex::new(HashMap::new()),
67        }
68    }
69
70    /// Returns the counter for `topic`, creating it on first use.
71    fn counter(&self, topic: &str) -> Arc<AtomicU64> {
72        let mut map = self.counters.lock().expect("counter map poisoned");
73        Arc::clone(map.entry(topic.to_owned()).or_default())
74    }
75
76    /// Takes one slot for `topic` without blocking.
77    ///
78    /// The compare-exchange loop is what makes the cap hold: two enqueues racing
79    /// for the last slot cannot both see room and both take it.
80    fn take_slot(&self, topic: &str) -> Result<Arc<AtomicU64>, BackpressureError> {
81        let counter = self.counter(topic);
82        let mut current = counter.load(Ordering::Acquire);
83        loop {
84            if current >= self.max_per_topic {
85                return Err(BackpressureError::LimitReached {
86                    topic: topic.to_owned(),
87                });
88            }
89            match counter.compare_exchange_weak(
90                current,
91                current + 1,
92                Ordering::AcqRel,
93                Ordering::Acquire,
94            ) {
95                Ok(_) => return Ok(counter),
96                Err(actual) => current = actual,
97            }
98        }
99    }
100
101    /// Enqueues `payload` if the topic has room, returning
102    /// [`BackpressureError::LimitReached`] otherwise.
103    ///
104    /// The slot is released again if the queue itself rejects the job, so a
105    /// failing backend cannot leak capacity.
106    pub async fn try_enqueue<Q: Queue + ?Sized>(
107        &self,
108        queue: &Q,
109        topic: &str,
110        payload: Vec<u8>,
111    ) -> Result<(), BackpressureError> {
112        let counter = self.take_slot(topic)?;
113        match queue.enqueue(topic, payload).await {
114            Ok(()) => Ok(()),
115            Err(e) => {
116                counter.fetch_sub(1, Ordering::AcqRel);
117                Err(BackpressureError::Enqueue(e))
118            }
119        }
120    }
121
122    /// Returns one slot for `topic` after a job is acked or nacked.
123    ///
124    /// Saturates at zero, so an unmatched call cannot wrap the counter and hand
125    /// the topic unlimited capacity.
126    pub fn dec_finished(&self, topic: &str) {
127        let counter = self.counter(topic);
128        let mut current = counter.load(Ordering::Acquire);
129        while current > 0 {
130            match counter.compare_exchange_weak(
131                current,
132                current - 1,
133                Ordering::AcqRel,
134                Ordering::Acquire,
135            ) {
136                Ok(_) => return,
137                Err(actual) => current = actual,
138            }
139        }
140    }
141
142    /// Slots currently held for `topic`, i.e. un-acked jobs.
143    pub fn inflight(&self, topic: &str) -> u64 {
144        self.counter(topic).load(Ordering::Acquire)
145    }
146}
147
148/// Enqueues every payload, counting the ones rejected for lack of room.
149///
150/// A queue failure is returned rather than counted: it is not backpressure, and
151/// continuing past it would silently drop the rest of the batch.
152pub async fn enqueue_with_backpressure<Q: Queue + ?Sized>(
153    enforcer: &BackpressureEnforcer,
154    queue: &Q,
155    topic: &str,
156    payloads: Vec<Vec<u8>>,
157) -> Result<usize, BackpressureError> {
158    let mut rejected = 0;
159    for payload in payloads {
160        match enforcer.try_enqueue(queue, topic, payload).await {
161            Ok(()) => {}
162            Err(BackpressureError::LimitReached { .. }) => rejected += 1,
163            Err(e) => return Err(e),
164        }
165    }
166    Ok(rejected)
167}
168
169#[cfg(test)]
170mod tests {
171    use super::*;
172    use crate::in_memory::InMemoryQueue;
173
174    #[tokio::test]
175    async fn try_enqueue_within_limit_succeeds() {
176        let reg = BackpressureEnforcer::new(2);
177        let queue = InMemoryQueue::new();
178        assert!(reg.try_enqueue(&queue, "t", b"x".to_vec()).await.is_ok());
179        assert_eq!(reg.inflight("t"), 1);
180    }
181
182    #[tokio::test]
183    async fn try_enqueue_rejects_when_full() {
184        let reg = BackpressureEnforcer::new(1);
185        let queue = InMemoryQueue::new();
186
187        reg.try_enqueue(&queue, "t", b"x".to_vec()).await.unwrap();
188        assert!(matches!(
189            reg.try_enqueue(&queue, "t", b"y".to_vec()).await,
190            Err(BackpressureError::LimitReached { .. })
191        ));
192    }
193
194    #[tokio::test]
195    async fn finished_jobs_release_capacity() {
196        let reg = BackpressureEnforcer::new(1);
197        let queue = InMemoryQueue::new();
198
199        reg.try_enqueue(&queue, "t", b"x".to_vec()).await.unwrap();
200        reg.dec_finished("t");
201        assert_eq!(reg.inflight("t"), 0);
202        assert!(reg.try_enqueue(&queue, "t", b"y".to_vec()).await.is_ok());
203    }
204
205    #[tokio::test]
206    async fn topics_are_capped_independently() {
207        let reg = BackpressureEnforcer::new(1);
208        let queue = InMemoryQueue::new();
209
210        reg.try_enqueue(&queue, "a", b"x".to_vec()).await.unwrap();
211        assert!(reg.try_enqueue(&queue, "b", b"y".to_vec()).await.is_ok());
212    }
213
214    #[tokio::test]
215    async fn unmatched_finish_does_not_wrap_the_counter() {
216        let reg = BackpressureEnforcer::new(1);
217        reg.dec_finished("t");
218        reg.dec_finished("t");
219        assert_eq!(reg.inflight("t"), 0);
220    }
221}