Skip to main content

mytheclipse_queue/
batch.rs

1//! Batch job processor for bulk processing of queued jobs.
2//!
3//! [`BatchProcessor`] wraps a [`Queue`] and accumulates jobs per topic until
4//! either `batch_size` is reached or `batch_timeout` elapses, then dispatches
5//! them to a [`BatchJobHandler`] for bulk processing (e.g. bulk DB insert,
6//! bulk email send, batch index write).
7
8use std::pin::Pin;
9use std::sync::Arc;
10use std::time::Duration;
11
12use tokio::sync::{mpsc, Semaphore};
13
14use crate::error::JobError;
15use crate::job::Job;
16use crate::traits::Queue;
17
18/// A handler that processes a batch of jobs atomically.
19pub trait BatchJobHandler: Send + Sync {
20    fn handle_batch(
21        &self,
22        jobs: Vec<Job>,
23    ) -> Pin<Box<dyn std::future::Future<Output = Result<(), JobError>> + Send>>;
24}
25
26impl<F, Fut> BatchJobHandler for F
27where
28    F: Fn(Vec<Job>) -> Fut + Send + Sync,
29    Fut: std::future::Future<Output = Result<(), JobError>> + Send + 'static,
30{
31    fn handle_batch(
32        &self,
33        jobs: Vec<Job>,
34    ) -> Pin<Box<dyn std::future::Future<Output = Result<(), JobError>> + Send>> {
35        Box::pin((self)(jobs))
36    }
37}
38
39/// Configuration for [`BatchProcessor`].
40#[derive(Debug, Clone)]
41pub struct BatchConfig {
42    /// Max jobs per batch before flushing.
43    pub batch_size: usize,
44    /// Max time to wait before flushing a partial batch.
45    pub batch_timeout: Duration,
46    /// Max concurrent batch-processing tasks.
47    pub concurrency: usize,
48}
49
50impl Default for BatchConfig {
51    fn default() -> Self {
52        Self {
53            batch_size: 100,
54            batch_timeout: Duration::from_secs(5),
55            concurrency: 4,
56        }
57    }
58}
59
60/// Result of a completed batch flush.
61pub struct BatchFlush {
62    /// Number of jobs in the flushed batch.
63    pub count: usize,
64}
65
66/// A processor that batches jobs before dispatching them.
67pub struct BatchProcessor<Q: Queue + 'static> {
68    queue: Arc<Q>,
69    config: BatchConfig,
70    semaphore: Arc<Semaphore>,
71}
72
73impl<Q: Queue + 'static> BatchProcessor<Q> {
74    pub fn new(queue: Q, config: BatchConfig) -> Self {
75        let sem = Arc::new(Semaphore::new(config.concurrency.max(1)));
76        Self {
77            queue: Arc::new(queue),
78            config,
79            semaphore: sem,
80        }
81    }
82
83    /// Starts a batch processor for `topic` using `handler`.
84    pub fn start<H>(&self, topic: &str, handler: H)
85    where
86        H: BatchJobHandler + 'static,
87    {
88        let queue = Arc::clone(&self.queue);
89        let config = self.config.clone();
90        let semaphore = Arc::clone(&self.semaphore);
91        let handler: Arc<dyn BatchJobHandler> = Arc::new(handler);
92        let topic_owned = topic.to_string();
93
94        let (tx, mut rx): (mpsc::Sender<Job>, mpsc::Receiver<Job>) =
95            mpsc::channel(config.batch_size);
96
97        // Dequeue loop → forward to channel
98        {
99            let q = Arc::clone(&queue);
100            let t = topic_owned.clone();
101            let tx2 = tx.clone();
102            let poll = config.poll_timeout();
103            tokio::spawn(async move {
104                loop {
105                    match q.dequeue(&t, poll).await {
106                        Ok(Some(job)) => {
107                            if tx2.send(job).await.is_err() {
108                                // Processor dropped; re-enqueue remaining
109                                break;
110                            }
111                        }
112                        Ok(None) => {}
113                        Err(e) => {
114                            tracing::error!(queue_error = %e, "batch dequeue error");
115                            tokio::time::sleep(poll).await;
116                        }
117                    }
118                }
119            });
120        }
121
122        // Batch accumulation + flush loop
123        let h = handler;
124        tokio::spawn(async move {
125            loop {
126                let mut batch: Vec<Job> = Vec::with_capacity(config.batch_size);
127                let deadline = tokio::time::sleep(config.batch_timeout);
128                tokio::pin!(deadline);
129
130                // Fill batch
131                loop {
132                    if batch.len() >= config.batch_size {
133                        break;
134                    }
135                    tokio::select! {
136                        biased;
137                        job = rx.recv() => match job {
138                            Some(j) => batch.push(j),
139                            None => {
140                                // channel closed: drain remaining
141                                while let Ok(j) = rx.try_recv() {
142                                    batch.push(j);
143                                }
144                                if !batch.is_empty() {
145                                    Self::flush(&h, &semaphore, batch).await;
146                                }
147                                return;
148                            }
149                        },
150                        _ = &mut deadline => break,
151                    }
152                }
153
154                if !batch.is_empty() {
155                    Self::flush(&h, &semaphore, batch).await;
156                }
157                deadline
158                    .as_mut()
159                    .reset(tokio::time::Instant::now() + config.batch_timeout);
160            }
161        });
162
163        // Keep tx alive for the dequeue loop (it was cloned)
164        let _keep = tx;
165    }
166
167    async fn flush(handler: &Arc<dyn BatchJobHandler>, sem: &Arc<Semaphore>, batch: Vec<Job>) {
168        let permit = match sem.clone().acquire_owned().await {
169            Ok(permit) => permit,
170            Err(_) => {
171                tracing::error!("batch semaphore closed");
172                return;
173            }
174        };
175        let h = Arc::clone(handler);
176        let batch_len = batch.len();
177        tokio::spawn(async move {
178            // Hold the permit for the duration of the batch: dropping it here
179            // (as a `flush`-local) would make `concurrency` a no-op.
180            let _permit = permit;
181            match h.handle_batch(batch).await {
182                Ok(()) => tracing::debug!(count = batch_len, "batch processed"),
183                Err(e) => tracing::error!("batch handler error: {}", e),
184            }
185        });
186    }
187}
188
189impl BatchConfig {
190    fn poll_timeout(&self) -> Duration {
191        self.batch_timeout.min(Duration::from_millis(100))
192    }
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198    use crate::in_memory::InMemoryQueue;
199    use std::sync::atomic::{AtomicUsize, Ordering};
200    use std::sync::Arc as StdArc;
201
202    fn make_queue() -> InMemoryQueue {
203        InMemoryQueue::new()
204    }
205
206    #[tokio::test]
207    async fn flush_on_batch_size() {
208        let queue = make_queue();
209        let counter = StdArc::new(AtomicUsize::new(0));
210        let cfg = BatchConfig {
211            batch_size: 3,
212            batch_timeout: Duration::from_secs(10),
213            concurrency: 2,
214        };
215        let bp = BatchProcessor::new(queue, cfg);
216        let c2 = StdArc::clone(&counter);
217        bp.start("t", move |jobs: Vec<Job>| {
218            let c3 = StdArc::clone(&c2);
219            Box::pin(async move {
220                c3.fetch_add(jobs.len(), Ordering::SeqCst);
221                Ok(())
222            })
223        });
224
225        for i in 0..3 {
226            bp.queue
227                .enqueue("t", format!("job{}", i).into_bytes())
228                .await
229                .unwrap();
230        }
231
232        tokio::time::sleep(Duration::from_millis(300)).await;
233        assert_eq!(counter.load(Ordering::SeqCst), 3);
234    }
235
236    #[tokio::test]
237    async fn flush_on_timeout() {
238        let queue = make_queue();
239        let queue2 = queue.clone();
240        let counter = StdArc::new(AtomicUsize::new(0));
241        let cfg = BatchConfig {
242            batch_size: 100,
243            batch_timeout: Duration::from_millis(100),
244            concurrency: 2,
245        };
246        let bp = BatchProcessor::new(queue, cfg);
247        let c2 = StdArc::clone(&counter);
248        bp.start("t", move |jobs: Vec<Job>| {
249            let c3 = StdArc::clone(&c2);
250            Box::pin(async move {
251                c3.fetch_add(jobs.len(), Ordering::SeqCst);
252                Ok(())
253            })
254        });
255
256        queue2.enqueue("t", b"x".to_vec()).await.unwrap();
257
258        tokio::time::sleep(Duration::from_millis(300)).await;
259        assert_eq!(counter.load(Ordering::SeqCst), 1);
260    }
261}