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#[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 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
66pub const MAX_SPLIT_CHUNKS: usize = 100_000;
73
74pub 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 pub fn with_split_cap(mut self, cap: usize) -> Self {
92 self.split_cap = cap;
93 self
94 }
95
96 fn batch_target_bytes(&self) -> usize {
100 (self.budget.bytes() / 64).max(1)
101 }
102
103 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 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 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 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 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 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 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 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 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 #[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 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 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}