Skip to main content

rypipe_core/
bounded.rs

1#[cfg(feature = "mmap")]
2use std::io::{Read, Seek, SeekFrom};
3use std::ops::Range;
4use std::path::Path;
5use std::sync::Arc;
6
7use arrow::record_batch::RecordBatch;
8
9use crate::arrow_export::apply_compare_filter;
10use crate::budget::{BudgetLedger, StreamStats};
11use crate::consumer::CollectingConsumer;
12use crate::decoder::{split_points_to_ranges, RecordParser, Splitter};
13use crate::engine::TableBuilder;
14use crate::input::InputBuffer;
15use crate::plan::ExecutionPlan;
16use crate::Result;
17
18/// A memory budget expressed in bytes.
19#[derive(Clone, Copy, Debug)]
20pub struct MemoryBudget {
21    bytes: usize,
22    strict: bool,
23}
24
25impl MemoryBudget {
26    pub fn new(bytes: usize) -> Self {
27        Self {
28            bytes,
29            strict: false,
30        }
31    }
32
33    pub fn bytes(&self) -> usize {
34        self.bytes
35    }
36
37    /// Fail when an executor memory check exceeds its allocation allowance.
38    /// This does not impose an OS limit on process RSS or adapter-owned memory.
39    pub fn with_strict(mut self, strict: bool) -> Self {
40        self.strict = strict;
41        self
42    }
43
44    pub fn is_strict(&self) -> bool {
45        self.strict
46    }
47
48    pub(crate) fn share(self, count: usize) -> Self {
49        Self {
50            bytes: self.bytes / count.max(1),
51            ..self
52        }
53    }
54
55    pub(crate) fn check(self, used: usize) -> Result<()> {
56        if self.strict && used > self.bytes {
57            return Err(crate::Error::Memory {
58                used,
59                limit: self.bytes,
60            });
61        }
62        Ok(())
63    }
64}
65
66/// Internal safeguard: never request more than this many split points, so a
67/// pathological row-size estimate cannot explode per-chunk overhead. The
68/// batch count is otherwise derived from the budget, input size, and
69/// estimated bytes per row; batches may still exceed the budget when the
70/// required count exceeds this cap. Increased for 64KB streaming (50GB/64KB
71/// ≈ 800k batches); still bounded by file scan cost.
72pub const MAX_SPLIT_CHUNKS: usize = 100_000;
73
74/// Parse an input in bounded batches to stay within a memory budget.
75pub struct BoundedExecutor {
76    budget: MemoryBudget,
77    split_cap: usize,
78}
79
80impl BoundedExecutor {
81    pub fn new(budget: MemoryBudget) -> Self {
82        Self {
83            budget,
84            split_cap: MAX_SPLIT_CHUNKS,
85        }
86    }
87
88    /// Override the split cap (default [`MAX_SPLIT_CHUNKS`]). Raising it may be
89    /// needed for very large files with small budgets, where capped batches
90    /// would otherwise overshoot the budget.
91    pub fn with_split_cap(mut self, cap: usize) -> Self {
92        self.split_cap = cap;
93        self
94    }
95
96    /// Payload bytes the executor targets per emitted batch. Exported
97    /// batches are exact-sized, so a single-record batch larger than this
98    /// is a flagged oversize batch (see [`StreamStats::oversize_batches`]).
99    fn batch_target_bytes(&self) -> usize {
100        (self.budget.bytes() / 64).max(1)
101    }
102
103    /// Derive chunk ranges and batch sizing from an in-memory sample of the
104    /// input. Returns `(chunk_ranges, rows_per_batch, bytes_per_row)`.
105    fn plan_chunks(
106        &self,
107        bytes: &[u8],
108        splitter: &dyn Splitter,
109    ) -> (Vec<Range<usize>>, usize, usize) {
110        let bytes_per_row = splitter
111            .estimate_bytes_per_row(&bytes[..bytes.len().min(65536)])
112            .max(1);
113        // Input, growing columns, merge buffers and Arrow output overlap.
114        let batch_bytes = self.batch_target_bytes();
115        let total_rows_est = bytes.len() / bytes_per_row;
116        let rows_per_batch = (batch_bytes / bytes_per_row)
117            .max(1)
118            .min(total_rows_est.max(1));
119
120        let num_batches = bytes.len().div_ceil(batch_bytes).max(1);
121        let capped = num_batches.min(self.split_cap);
122        let split_points = splitter.find_split_points(bytes, capped);
123        let chunks = split_points_to_ranges(&split_points, bytes.len());
124        (chunks, rows_per_batch, bytes_per_row)
125    }
126
127    fn parse_chunk<P>(
128        parser: &P,
129        bytes: &[u8],
130        plan: Arc<ExecutionPlan>,
131        bytes_per_row: usize,
132        budget: MemoryBudget,
133    ) -> Result<TableBuilder>
134    where
135        P: RecordParser,
136    {
137        budget.check(bytes.len())?;
138        let mut engine =
139            TableBuilder::with_plan((bytes.len() / bytes_per_row.max(512)).max(64), plan);
140        engine.set_memory_budget(budget)?;
141        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
142            parser.validate(bytes)?;
143            parser.parse_chunk_generic(bytes, &mut engine)
144        }))
145        .unwrap_or_else(|payload| {
146            let msg = if let Some(s) = payload.downcast_ref::<&str>() {
147                (*s).to_string()
148            } else if let Some(s) = payload.downcast_ref::<String>() {
149                s.clone()
150            } else {
151                "unknown panic".to_string()
152            };
153            Err(crate::Error::Parser(format!(
154                "worker panicked during bounded parse: {msg}"
155            )))
156        })?;
157        engine.check_memory_budget()?;
158        Ok(engine)
159    }
160
161    fn consume_batch<C: crate::consumer::BatchConsumer>(
162        &self,
163        mut engine: TableBuilder,
164        plan: &ExecutionPlan,
165        consumer: &mut C,
166        ledger: &mut BudgetLedger,
167        stats: &mut StreamStats,
168    ) -> Result<()> {
169        let mut batch = engine.finish()?;
170        if let Some(ref filter) = plan.filter {
171            batch = apply_compare_filter(batch, filter)?;
172        }
173        let batch_bytes = batch.get_array_memory_size();
174        self.budget.share(4).check(batch_bytes)?;
175        if batch.num_rows() == 1 && batch_bytes > self.batch_target_bytes() {
176            stats.oversize_batches += 1;
177        }
178        let rows = batch.num_rows();
179        ledger.charge_in_flight(batch_bytes);
180        let res = consumer.consume(batch);
181        ledger.release_in_flight(batch_bytes);
182        res?;
183        stats.batches += 1;
184        stats.rows += rows;
185        Ok(())
186    }
187
188    fn consume_chunks<I, C>(
189        &self,
190        chunks: I,
191        rows_per_batch: usize,
192        plan: Arc<ExecutionPlan>,
193        consumer: &mut C,
194        ledger: &mut BudgetLedger,
195        stats: &mut StreamStats,
196    ) -> Result<()>
197    where
198        I: IntoIterator<Item = Result<TableBuilder>>,
199        C: crate::consumer::BatchConsumer,
200    {
201        let mut batch_engine = TableBuilder::with_plan(rows_per_batch.min(64), Arc::clone(&plan));
202        batch_engine.set_memory_budget(self.budget.share(4))?;
203        let mut rows_in_batch = 0usize;
204        for chunk_engine in chunks {
205            let chunk_engine = chunk_engine?;
206            let chunk_rows = chunk_engine.num_rows();
207            ledger.set_builders(
208                batch_engine
209                    .capacity_bytes()
210                    .saturating_add(chunk_engine.capacity_bytes()),
211            );
212            let rows_per_batch = rows_per_batch.min(
213                (self.budget.bytes() / 8)
214                    .saturating_mul(chunk_rows)
215                    .checked_div(chunk_engine.capacity_bytes().max(1))
216                    .unwrap_or(1)
217                    .max(1),
218            );
219            if rows_in_batch > 0
220                && batch_engine
221                    .capacity_bytes()
222                    .saturating_add(chunk_engine.capacity_bytes())
223                    > self.budget.bytes() / 4
224            {
225                let batch = batch_engine.split_off(batch_engine.num_rows());
226                self.consume_batch(batch, &plan, consumer, ledger, stats)?;
227                ledger.set_builders(batch_engine.capacity_bytes());
228                rows_in_batch = 0;
229            }
230            batch_engine.extend(chunk_engine)?;
231            batch_engine.check_memory_budget()?;
232            ledger.set_builders(batch_engine.capacity_bytes());
233            rows_in_batch += chunk_rows;
234            while rows_in_batch >= rows_per_batch
235                || batch_engine.bytes_used() >= self.budget.bytes()
236            {
237                if batch_engine.num_rows() == 0 {
238                    break;
239                }
240                let n = rows_per_batch.min(batch_engine.num_rows());
241                let n = if batch_engine.bytes_used() >= self.budget.bytes()
242                    && batch_engine.num_rows() > 1
243                {
244                    let est = (batch_engine.num_rows() as f64 * self.budget.bytes() as f64
245                        / batch_engine.bytes_used() as f64) as usize;
246                    est.clamp(1, n)
247                } else {
248                    n
249                };
250                self.consume_batch(batch_engine.split_off(n), &plan, consumer, ledger, stats)?;
251                ledger.set_builders(batch_engine.capacity_bytes());
252                rows_in_batch = rows_in_batch.saturating_sub(n);
253            }
254        }
255        if let Some(err) = batch_engine.unknown_error.take() {
256            return Err(crate::Error::Merge(err));
257        }
258        if let Some(err) = batch_engine.strict_error.take() {
259            return Err(err);
260        }
261        if batch_engine.num_rows() > 0 {
262            self.consume_batch(batch_engine, &plan, consumer, ledger, stats)?;
263        }
264        Ok(())
265    }
266
267    /// Parse an in-memory byte slice in bounded batches, calling `consumer` per batch.
268    ///
269    /// Chunks are sliced directly from `bytes`; no file I/O occurs. This is
270    /// the streaming entry point for adapters holding decompressed data.
271    /// The budget controls batch sizing; allocator, parser, input, and Arrow
272    /// overhead can raise process RSS above this target.
273    pub fn run_bytes_stream<P, C>(
274        &self,
275        bytes: &[u8],
276        splitter: &dyn Splitter,
277        parser: P,
278        plan: Arc<ExecutionPlan>,
279        consumer: &mut C,
280    ) -> Result<()>
281    where
282        P: RecordParser + Clone + Send + Sync,
283        C: crate::consumer::BatchConsumer,
284    {
285        self.run_bytes_stream_with_stats(bytes, splitter, parser, plan, consumer)
286            .map(|_| ())
287    }
288
289    /// Like [`BoundedExecutor::run_bytes_stream`], but reports a
290    /// [`StreamStats`] summary including the peak tracked engine memory.
291    ///
292    /// The input slice is caller-owned, so it is not charged to the ledger;
293    /// `peak_tracked_bytes` covers builders and in-flight batches only.
294    pub fn run_bytes_stream_with_stats<P, C>(
295        &self,
296        bytes: &[u8],
297        splitter: &dyn Splitter,
298        parser: P,
299        plan: Arc<ExecutionPlan>,
300        consumer: &mut C,
301    ) -> Result<StreamStats>
302    where
303        P: RecordParser + Clone + Send + Sync,
304        C: crate::consumer::BatchConsumer,
305    {
306        let mut ledger = BudgetLedger::new(self.budget);
307        let mut stats = StreamStats::default();
308        self.run_bytes_stream_inner(
309            bytes,
310            splitter,
311            parser,
312            plan,
313            consumer,
314            &mut ledger,
315            &mut stats,
316        )?;
317        stats.peak_tracked_bytes = ledger.peak();
318        Ok(stats)
319    }
320
321    #[allow(clippy::too_many_arguments)]
322    fn run_bytes_stream_inner<P, C>(
323        &self,
324        bytes: &[u8],
325        splitter: &dyn Splitter,
326        parser: P,
327        plan: Arc<ExecutionPlan>,
328        consumer: &mut C,
329        ledger: &mut BudgetLedger,
330        stats: &mut StreamStats,
331    ) -> Result<()>
332    where
333        P: RecordParser + Clone + Send + Sync,
334        C: crate::consumer::BatchConsumer,
335    {
336        if bytes.is_empty() {
337            return Ok(());
338        }
339
340        let (mut chunks, rows_per_batch, bytes_per_row) = self.plan_chunks(bytes, splitter);
341
342        // Guard against degenerate splitter output that produces no ranges.
343        if chunks.is_empty() {
344            chunks.push(0..bytes.len());
345        }
346
347        let parse_plan = Arc::clone(&plan);
348        let budget = self.budget.share(4);
349        budget.check(chunks.capacity() * std::mem::size_of::<Range<usize>>())?;
350        let chunks = chunks.into_iter().map(move |chunk| {
351            Self::parse_chunk(
352                &parser,
353                &bytes[chunk.start..chunk.end],
354                Arc::clone(&parse_plan),
355                bytes_per_row,
356                budget,
357            )
358        });
359        self.consume_chunks(chunks, rows_per_batch, plan, consumer, ledger, stats)
360    }
361
362    /// Parse an in-memory byte slice in bounded batches, returning one
363    /// `RecordBatch` per batch.
364    ///
365    /// Chunks are sliced directly from `bytes`; no file I/O occurs. This is
366    /// the entry point for adapters holding decompressed or streamed-in data.
367    pub fn run_bytes<P>(
368        &self,
369        bytes: &[u8],
370        splitter: &dyn Splitter,
371        parser: P,
372        plan: Arc<ExecutionPlan>,
373    ) -> Result<Vec<RecordBatch>>
374    where
375        P: RecordParser + Clone + Send + Sync,
376    {
377        let batches = Vec::new();
378        let mut consumer = CollectingConsumer(batches);
379        self.run_bytes_stream(bytes, splitter, parser, plan, &mut consumer)?;
380        consumer.finish()
381    }
382
383    /// Parse `path` in batches, calling `consumer` per batch (streaming).
384    ///
385    /// Compressed inputs are decompressed up front and served via
386    /// `run_bytes_stream`. Uncompressed inputs with `mmap` use the seek-based
387    /// path with a reusable chunk buffer to keep RSS constant.
388    pub fn run_stream<P, C>(
389        &self,
390        path: &Path,
391        splitter: &dyn Splitter,
392        parser: P,
393        plan: Arc<ExecutionPlan>,
394        prefault: bool,
395        consumer: &mut C,
396    ) -> Result<()>
397    where
398        P: RecordParser + Clone + Send + Sync,
399        C: crate::consumer::BatchConsumer,
400    {
401        self.run_stream_with_stats(path, splitter, parser, plan, prefault, consumer)
402            .map(|_| ())
403    }
404
405    /// Like [`BoundedExecutor::run_stream`], but reports a [`StreamStats`]
406    /// summary including the peak tracked engine memory.
407    pub fn run_stream_with_stats<P, C>(
408        &self,
409        path: &Path,
410        splitter: &dyn Splitter,
411        parser: P,
412        plan: Arc<ExecutionPlan>,
413        prefault: bool,
414        consumer: &mut C,
415    ) -> Result<StreamStats>
416    where
417        P: RecordParser + Clone + Send + Sync,
418        C: crate::consumer::BatchConsumer,
419    {
420        let mut ledger = BudgetLedger::new(self.budget);
421        let mut stats = StreamStats::default();
422        let use_mmap = cfg!(feature = "mmap");
423        let input = InputBuffer::open(path, use_mmap, prefault)?;
424
425        #[cfg(feature = "mmap")]
426        if matches!(input, InputBuffer::Mmap(_)) {
427            self.run_mapped_stream(
428                input,
429                splitter,
430                parser,
431                plan,
432                consumer,
433                &mut ledger,
434                &mut stats,
435            )?;
436            stats.peak_tracked_bytes = ledger.peak();
437            return Ok(stats);
438        }
439
440        self.budget.share(4).check(input.len())?;
441        ledger.set_input(input.len());
442        self.run_bytes_stream_inner(
443            input.as_slice(),
444            splitter,
445            parser,
446            plan,
447            consumer,
448            &mut ledger,
449            &mut stats,
450        )?;
451        stats.peak_tracked_bytes = ledger.peak();
452        Ok(stats)
453    }
454
455    /// Parse `path` in batches, returning one `RecordBatch` per batch.
456    ///
457    /// The caller is responsible for concatenating the batches if a single
458    /// table is desired.
459    ///
460    /// Compressed inputs (see [`InputBuffer::open`]) are decompressed up
461    /// front and served from memory via [`BoundedExecutor::run_bytes`].
462    /// Uncompressed inputs on platforms with the `mmap` feature retain the
463    /// seek-based path: the mapping is dropped after planning and each chunk
464    /// is read from disk on demand, keeping resident memory low.
465    pub fn run<P>(
466        &self,
467        path: &Path,
468        splitter: &dyn Splitter,
469        parser: P,
470        plan: Arc<ExecutionPlan>,
471        prefault: bool,
472    ) -> Result<Vec<RecordBatch>>
473    where
474        P: RecordParser + Clone + Send + Sync,
475    {
476        let batches = Vec::new();
477        let mut consumer = CollectingConsumer(batches);
478        self.run_stream(path, splitter, parser, plan, prefault, &mut consumer)?;
479        consumer.finish()
480    }
481
482    /// Streaming path for mapped inputs: plan against the mapping, drop it,
483    /// then read each chunk with a reusable buffer.
484    #[cfg(feature = "mmap")]
485    #[allow(clippy::too_many_arguments)]
486    fn run_mapped_stream<P, C>(
487        &self,
488        input: InputBuffer,
489        splitter: &dyn Splitter,
490        parser: P,
491        plan: Arc<ExecutionPlan>,
492        consumer: &mut C,
493        ledger: &mut BudgetLedger,
494        stats: &mut StreamStats,
495    ) -> Result<()>
496    where
497        P: RecordParser + Clone + Send + Sync,
498        C: crate::consumer::BatchConsumer,
499    {
500        let bytes = input.as_slice();
501        if bytes.is_empty() {
502            return Ok(());
503        }
504
505        let (mut chunks, rows_per_batch, bytes_per_row) = self.plan_chunks(bytes, splitter);
506
507        // Guard against degenerate splitter output that produces no ranges.
508        if chunks.is_empty() {
509            chunks.push(0..bytes.len());
510        }
511
512        let InputBuffer::Mmap(handle) = input else {
513            unreachable!("mapped input required");
514        };
515        let mut file = handle.file;
516        drop(handle.mmap);
517
518        // Reusable buffer sized to the largest chunk to avoid per-chunk alloc.
519        let max_chunk = chunks.iter().map(|r| r.len()).max().unwrap_or(0);
520        let budget = self.budget.share(4);
521        budget.check(
522            max_chunk.saturating_add(chunks.capacity() * std::mem::size_of::<Range<usize>>()),
523        )?;
524        let mut chunk_buf = Vec::with_capacity(max_chunk);
525        ledger.set_input(chunk_buf.capacity());
526
527        let parse_plan = Arc::clone(&plan);
528        let parsed_chunks = chunks.into_iter().map(move |chunk| {
529            let chunk_len = chunk.len();
530            chunk_buf.resize(chunk_len, 0);
531            file.seek(SeekFrom::Start(chunk.start as u64))?;
532            file.read_exact(&mut chunk_buf)?;
533            Self::parse_chunk(
534                &parser,
535                &chunk_buf,
536                Arc::clone(&parse_plan),
537                bytes_per_row,
538                budget,
539            )
540        });
541        self.consume_chunks(parsed_chunks, rows_per_batch, plan, consumer, ledger, stats)
542    }
543}
544
545#[cfg(test)]
546mod tests {
547    use super::*;
548    use crate::decoder::Splitter;
549    use crate::ExecutionPlan;
550
551    struct NewlineSplitter;
552
553    impl Splitter for NewlineSplitter {
554        fn next_record_start(&self, bytes: &[u8], from: usize) -> Option<usize> {
555            if from == 0 && !bytes.is_empty() {
556                return Some(0);
557            }
558            bytes[from.saturating_sub(1)..]
559                .iter()
560                .position(|&b| b == b'\n')
561                .map(|i| from + i + 1)
562                .filter(|&p| p < bytes.len())
563        }
564
565        fn estimate_bytes_per_row(&self, sample: &[u8]) -> usize {
566            let newlines = sample.iter().filter(|&&b| b == b'\n').count().max(1);
567            (sample.len() / newlines).max(1)
568        }
569    }
570
571    fn rows(n: usize) -> Vec<u8> {
572        "abcdefghij\n".repeat(n).into_bytes()
573    }
574
575    #[test]
576    fn test_split_cap_limits_chunk_count() {
577        let data = rows(10_000);
578        let budget = MemoryBudget::new(1024);
579
580        let default_chunks = BoundedExecutor::new(budget)
581            .plan_chunks(&data, &NewlineSplitter)
582            .0
583            .len();
584        assert!(
585            default_chunks > 2,
586            "uncapped run must split: {default_chunks}"
587        );
588
589        for cap in [1, 2, 3] {
590            let chunks = BoundedExecutor::new(budget)
591                .with_split_cap(cap)
592                .plan_chunks(&data, &NewlineSplitter)
593                .0;
594            assert!(
595                chunks.len() <= cap.max(1),
596                "cap {cap} must bound chunk count, got {}",
597                chunks.len()
598            );
599        }
600    }
601
602    #[test]
603    fn test_default_split_cap_is_max_split_chunks() {
604        assert_eq!(
605            BoundedExecutor::new(MemoryBudget::new(1)).split_cap,
606            MAX_SPLIT_CHUNKS
607        );
608        let plan = ExecutionPlan::new().with_max_split_chunks(7);
609        assert_eq!(plan.max_split_chunks, Some(7));
610        assert_eq!(ExecutionPlan::new().max_split_chunks, None);
611    }
612}