Skip to main content

mytheclipse_queue/
backpressure_enqueue.rs

1//! Backpressure-aware enqueuer (in-memory backend).
2//!
3//! [`BackpressureEnforcer`] tracks in-flight jobs and caps the number of
4//! pending enqueues per topic, returning [`BackpressureError`] instead of
5//! blocking when the cap is exceeded.
6
7use std::sync::atomic::{AtomicU64, Ordering};
8use std::sync::Arc;
9
10use tokio::sync::Semaphore;
11
12use crate::traits::Queue;
13
14/// Errors returned by [`BackpressureEnforcer`].
15#[derive(Debug)]
16pub enum BackpressureError {
17    /// The configured in-flight cap was reached; enqueue rejected.
18    LimitReached { topic: String },
19}
20
21impl std::fmt::Display for BackpressureError {
22    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
23        match self {
24            Self::LimitReached { topic } => {
25                write!(f, "backpressure: in-flight limit reached for topic {topic}")
26            }
27        }
28    }
29}
30
31impl std::error::Error for BackpressureError {}
32
33/// Enforces a maximum number of in-flight jobs per topic.
34pub struct BackpressureEnforcer {
35    /// Maximum number of in-flight (un-acked) jobs system-wide (capacity hint).
36    #[allow(dead_code)]
37    max_inflight: usize,
38    /// Per-topic in-flight counter.
39    counters: Arc<std::sync::Mutex<std::collections::HashMap<String, Arc<AtomicU64>>>>,
40    /// Bounded semaphore enforcing total concurrency.
41    #[allow(dead_code)]
42    global: Arc<Semaphore>,
43}
44
45impl BackpressureEnforcer {
46    /// Creates an enforcer with a global maximum of `max_inflight` concurrent
47    /// in-flight jobs.
48    pub fn new(max_inflight: usize) -> Self {
49        Self {
50            max_inflight,
51            counters: Arc::new(std::sync::Mutex::new(std::collections::HashMap::new())),
52            global: Arc::new(Semaphore::new(max_inflight.max(1))),
53        }
54    }
55
56    /// Returns the per-topic in-flight count, creating zero if absent.
57    fn get_counter(&self, topic: &str) -> Arc<AtomicU64> {
58        let mut map = self.counters.lock().unwrap();
59        map.entry(topic.to_string())
60            .or_insert_with(|| Arc::new(AtomicU64::new(0)));
61        Arc::clone(map.get(topic).unwrap())
62    }
63
64    /// Attempts to acquire a backpressure slot non-blockingly.
65    /// Returns Err if at capacity.
66    pub async fn try_enqueue<Q: Queue + ?Sized>(
67        &self,
68        queue: &Q,
69        topic: &str,
70        payload: Vec<u8>,
71    ) -> Result<(), BackpressureError> {
72        // Per-topic counter increment (informational; global semaphore is the hard limit)
73        let counter = self.get_counter(topic);
74        counter.fetch_add(1, Ordering::SeqCst);
75
76        // Try global semaphore non-blocking
77        match self.global.clone().try_acquire_owned() {
78            Ok(_permit) => {
79                let _ = queue.enqueue(topic, payload).await;
80                Ok(())
81            }
82            Err(_) => {
83                counter.fetch_sub(1, Ordering::SeqCst);
84                Err(BackpressureError::LimitReached {
85                    topic: topic.to_string(),
86                })
87            }
88        }
89    }
90
91    /// Increments the in-flight counter when a job is delivered.
92    pub fn inc_delivered(&self, topic: &str) {
93        self.get_counter(topic).fetch_add(1, Ordering::SeqCst);
94    }
95
96    /// Decrements the in-flight counter after a job is acked/nacked.
97    pub fn dec_finished(&self, topic: &str) {
98        self.get_counter(topic).fetch_sub(1, Ordering::SeqCst);
99    }
100
101    /// Current in-flight count for a topic.
102    pub fn inflight(&self, topic: &str) -> u64 {
103        self.get_counter(topic).load(Ordering::SeqCst)
104    }
105}
106
107/// Helper: enqueue with backpressure, returning how many were rejected.
108pub async fn enqueue_with_backpressure<Q: Queue + ?Sized>(
109    enforcer: &BackpressureEnforcer,
110    queue: &Q,
111    topic: &str,
112    payloads: Vec<Vec<u8>>,
113) -> Result<usize, BackpressureError> {
114    let mut rejected = 0;
115    for payload in payloads {
116        if enforcer.try_enqueue(queue, topic, payload).await.is_err() {
117            rejected += 1;
118        }
119    }
120    Ok(rejected)
121}
122
123#[cfg(test)]
124mod tests {
125    use super::*;
126    use crate::in_memory::InMemoryQueue;
127
128    #[tokio::test]
129    async fn try_enqueue_within_limit_succeeds() {
130        let reg = BackpressureEnforcer::new(2);
131        let queue = InMemoryQueue::new();
132        let result = reg.try_enqueue(&queue, "t", b"x".to_vec()).await;
133        assert!(result.is_ok());
134    }
135
136    #[tokio::test]
137    async fn try_enqueue_rejects_when_full() {
138        let reg = BackpressureEnforcer::new(1);
139        let queue = InMemoryQueue::new();
140
141        // acquire the single global permit without releasing
142        let _first = reg.global.clone().acquire_owned().await.unwrap();
143
144        let result = reg.try_enqueue(&queue, "t", b"x".to_vec()).await;
145        assert!(matches!(
146            result,
147            Err(BackpressureError::LimitReached { .. })
148        ));
149    }
150}