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 = sem.clone().acquire_owned().await;
169        if permit.is_err() {
170            tracing::error!("batch semaphore closed");
171            return;
172        }
173        let _permit = permit.unwrap();
174        let h = Arc::clone(handler);
175        let batch_len = batch.len();
176        tokio::spawn(async move {
177            match h.handle_batch(batch).await {
178                Ok(()) => tracing::debug!(count = batch_len, "batch processed"),
179                Err(e) => tracing::error!("batch handler error: {}", e),
180            }
181        });
182    }
183}
184
185impl BatchConfig {
186    fn poll_timeout(&self) -> Duration {
187        self.batch_timeout.min(Duration::from_millis(100))
188    }
189}
190
191#[cfg(test)]
192mod tests {
193    use super::*;
194    use crate::in_memory::InMemoryQueue;
195    use std::sync::atomic::{AtomicUsize, Ordering};
196    use std::sync::Arc as StdArc;
197
198    fn make_queue() -> InMemoryQueue {
199        InMemoryQueue::new()
200    }
201
202    #[tokio::test]
203    async fn flush_on_batch_size() {
204        let queue = make_queue();
205        let counter = StdArc::new(AtomicUsize::new(0));
206        let cfg = BatchConfig {
207            batch_size: 3,
208            batch_timeout: Duration::from_secs(10),
209            concurrency: 2,
210        };
211        let bp = BatchProcessor::new(queue, cfg);
212        let c2 = StdArc::clone(&counter);
213        bp.start("t", move |jobs: Vec<Job>| {
214            let c3 = StdArc::clone(&c2);
215            Box::pin(async move {
216                c3.fetch_add(jobs.len(), Ordering::SeqCst);
217                Ok(())
218            })
219        });
220
221        for i in 0..3 {
222            bp.queue
223                .enqueue("t", format!("job{}", i).into_bytes())
224                .await
225                .unwrap();
226        }
227
228        tokio::time::sleep(Duration::from_millis(300)).await;
229        assert_eq!(counter.load(Ordering::SeqCst), 3);
230    }
231
232    #[tokio::test]
233    async fn flush_on_timeout() {
234        let queue = make_queue();
235        let queue2 = queue.clone();
236        let counter = StdArc::new(AtomicUsize::new(0));
237        let cfg = BatchConfig {
238            batch_size: 100,
239            batch_timeout: Duration::from_millis(100),
240            concurrency: 2,
241        };
242        let bp = BatchProcessor::new(queue, cfg);
243        let c2 = StdArc::clone(&counter);
244        bp.start("t", move |jobs: Vec<Job>| {
245            let c3 = StdArc::clone(&c2);
246            Box::pin(async move {
247                c3.fetch_add(jobs.len(), Ordering::SeqCst);
248                Ok(())
249            })
250        });
251
252        queue2.enqueue("t", b"x".to_vec()).await.unwrap();
253
254        tokio::time::sleep(Duration::from_millis(300)).await;
255        assert_eq!(counter.load(Ordering::SeqCst), 1);
256    }
257}