qubit_batch/process/impls/
chunked_batch_processor_builder.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10use std::{
11    num::NonZeroUsize,
12    sync::Arc,
13    time::Duration,
14};
15
16use qubit_progress::reporter::{
17    NoOpProgressReporter,
18    ProgressReporter,
19};
20
21use super::ChunkedBatchProcessor;
22
23/// Builder for [`ChunkedBatchProcessor`].
24///
25/// Use the builder when the default progress interval or reporter should be
26/// customized.
27///
28/// ```rust
29/// use std::{
30///     num::NonZeroUsize,
31///     time::Duration,
32/// };
33///
34/// use qubit_batch::{
35///     ChunkedBatchProcessor,
36///     SequentialBatchProcessor,
37/// };
38///
39/// let delegate = SequentialBatchProcessor::new(|_item: &i32| {});
40/// let processor = ChunkedBatchProcessor::builder(
41///     delegate,
42///     NonZeroUsize::new(2).expect("chunk size should be non-zero"),
43/// )
44/// .report_interval(Duration::ZERO)
45/// .build();
46///
47/// assert_eq!(processor.chunk_size().get(), 2);
48/// assert_eq!(processor.report_interval(), Duration::ZERO);
49/// ```
50pub struct ChunkedBatchProcessorBuilder<P> {
51    /// Delegate processor receiving each chunk.
52    delegate: P,
53    /// Maximum number of items submitted to the delegate at once.
54    chunk_size: NonZeroUsize,
55    /// Minimum interval between progress callbacks.
56    report_interval: Duration,
57    /// Reporter receiving batch lifecycle callbacks.
58    reporter: Arc<dyn ProgressReporter>,
59}
60
61impl<P> ChunkedBatchProcessorBuilder<P> {
62    /// Creates a builder from a delegate and chunk size.
63    ///
64    /// # Parameters
65    ///
66    /// * `delegate` - Processor receiving each chunk.
67    /// * `chunk_size` - Maximum number of items submitted in one chunk.
68    ///
69    /// # Returns
70    ///
71    /// A builder initialized with default chunked processor settings.
72    #[inline]
73    pub fn new(delegate: P, chunk_size: NonZeroUsize) -> Self {
74        Self {
75            delegate,
76            chunk_size,
77            report_interval: ChunkedBatchProcessor::<P>::DEFAULT_REPORT_INTERVAL,
78            reporter: Arc::new(NoOpProgressReporter),
79        }
80    }
81
82    /// Sets the progress-report interval.
83    ///
84    /// # Parameters
85    ///
86    /// * `report_interval` - Minimum time between due-based running progress
87    ///   callbacks. [`Duration::ZERO`] reports at every completed-chunk
88    ///   progress point.
89    ///
90    /// # Returns
91    ///
92    /// This builder for fluent configuration.
93    #[inline]
94    pub const fn report_interval(mut self, report_interval: Duration) -> Self {
95        self.report_interval = report_interval;
96        self
97    }
98
99    /// Sets the progress reporter used by built processors.
100    ///
101    /// # Parameters
102    ///
103    /// * `reporter` - Progress reporter used for later processing calls.
104    ///
105    /// # Returns
106    ///
107    /// This builder for fluent configuration.
108    #[inline]
109    pub fn reporter<R>(mut self, reporter: R) -> Self
110    where
111        R: ProgressReporter + 'static,
112    {
113        self.reporter = Arc::new(reporter);
114        self
115    }
116
117    /// Sets the shared progress reporter used by built processors.
118    ///
119    /// # Parameters
120    ///
121    /// * `reporter` - Shared progress reporter used for later processing calls.
122    ///
123    /// # Returns
124    ///
125    /// This builder for fluent configuration.
126    #[inline]
127    pub fn reporter_arc(mut self, reporter: Arc<dyn ProgressReporter>) -> Self {
128        self.reporter = reporter;
129        self
130    }
131
132    /// Disables progress callbacks by using [`NoOpProgressReporter`].
133    ///
134    /// # Returns
135    ///
136    /// This builder for fluent configuration.
137    #[inline]
138    pub fn no_reporter(mut self) -> Self {
139        self.reporter = Arc::new(NoOpProgressReporter);
140        self
141    }
142
143    /// Builds a [`ChunkedBatchProcessor`].
144    ///
145    /// # Returns
146    ///
147    /// A chunked batch processor with this builder's configuration.
148    #[inline]
149    pub fn build(self) -> ChunkedBatchProcessor<P> {
150        ChunkedBatchProcessor {
151            delegate: self.delegate,
152            chunk_size: self.chunk_size,
153            report_interval: self.report_interval,
154            reporter: self.reporter,
155        }
156    }
157}
qubit_batch/process/impls/chunked_batch_processor_builder.rs

qubit_batch/process/impls/
chunked_batch_processor_builder.rs
