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