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