1use crate::dataset::Dataset;
2use incin_core::backend_authoring::Backend;
3use incin_core::backend_authoring::{Capabilities, Execute};
4use incin_core::error::{Error, ErrorMessage, Result as CoreResult};
5use incin_core::exec::catalog::op;
6use incin_core::shapes::{Dyn, DynShape, Shape};
7use incin_core::tensor::base::Tensor;
8use incin_core::tensor::device::Device;
9use incin_core::tensor::dtype::DType;
10use incin_core::tensor::grad::RequiresGrad;
11use rand::SeedableRng;
12use rand::rngs::StdRng;
13use rand::seq::SliceRandom;
14use std::collections::BTreeMap;
15use std::num::NonZeroUsize;
16use std::panic::{AssertUnwindSafe, catch_unwind};
17use std::sync::atomic::{AtomicBool, Ordering};
18use std::sync::mpsc::{Receiver, sync_channel};
19use std::sync::{Arc, Mutex};
20use std::thread::{self, JoinHandle};
21use std::time::Duration;
22
23#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
29pub enum DataError {
30 #[error("dataset error: {0}")]
32 Dataset(String),
33 #[error("dataset index {index} is outside length {len}")]
35 IndexOutOfBounds {
36 index: usize,
38 len: usize,
40 },
41 #[error("worker {worker_id} panicked while {stage}")]
43 WorkerPanicked {
44 worker_id: usize,
46 stage: &'static str,
48 },
49 #[error("worker {worker_id} panicked while collating")]
51 CollatePanicked {
52 worker_id: usize,
54 },
55 #[error("invalid batch: {0}")]
57 InvalidBatch(String),
58 #[error("data-loader worker disconnected")]
60 WorkerDisconnected,
61 #[error("data-loader timed out after {duration:?}")]
63 Timeout {
64 duration: Duration,
66 },
67 #[error("invalid input: {0}")]
69 InvalidInput(String),
70}
71
72pub type BatchResult<T> = core::result::Result<T, DataError>;
74
75pub trait Collate<T>: Send + Sync {
77 type Output: Send + 'static;
79 fn collate(&self, batch: Vec<T>) -> BatchResult<Self::Output>;
81}
82
83#[derive(Debug, Clone, Copy, Default)]
85pub struct DefaultCollate;
86
87macro_rules! impl_scalar_collate {
88 ($($ty:ty),+ $(,)?) => {
89 $(impl Collate<$ty> for DefaultCollate {
90 type Output = Vec<$ty>;
91
92 fn collate(&self, batch: Vec<$ty>) -> BatchResult<Self::Output> {
93 Ok(batch)
94 }
95 })+
96 };
97}
98
99impl_scalar_collate!(
100 bool, u8, u16, u32, u64, usize, i8, i16, i32, i64, isize, f32, f64, String
101);
102
103impl<T: Send + 'static> Collate<Vec<T>> for DefaultCollate {
104 type Output = Vec<Vec<T>>;
105
106 fn collate(&self, batch: Vec<Vec<T>>) -> BatchResult<Self::Output> {
107 Ok(batch)
108 }
109}
110
111impl<S, B, K, G> Collate<Tensor<S, B, K, G>> for DefaultCollate
112where
113 S: Shape + DynShape,
114 B: Backend + Execute<op::StackExact> + Capabilities,
115 K: DType,
116 G: RequiresGrad,
117 Tensor<S, B, K, G>: Send + 'static,
118 <B as Execute<op::StackExact>>::Output: Into<B::Storage<K>>,
119 B::Storage<K>: Send + 'static,
120 K::Field: Send + 'static,
121 <B::Device as Device>::Field: Send + 'static,
122{
123 type Output = Tensor<Dyn, B, K, G>;
124
125 fn collate(&self, batch: Vec<Tensor<S, B, K, G>>) -> BatchResult<Self::Output> {
126 let samples = batch.iter().collect::<Vec<_>>();
127 incin_core::tensor::ops::manipulation::try_stack_tensors(&samples, 0)
128 .map_err(|error| DataError::InvalidBatch(error.to_string()))
129 }
130}
131
132impl<A, B> Collate<(A, B)> for DefaultCollate
133where
134 A: Send + 'static,
135 B: Send + 'static,
136 DefaultCollate: Collate<A> + Collate<B>,
137{
138 type Output = (
139 <DefaultCollate as Collate<A>>::Output,
140 <DefaultCollate as Collate<B>>::Output,
141 );
142
143 fn collate(&self, batch: Vec<(A, B)>) -> BatchResult<Self::Output> {
144 let mut first = Vec::with_capacity(batch.len());
145 let mut second = Vec::with_capacity(batch.len());
146 for (a, b) in batch {
147 first.push(a);
148 second.push(b);
149 }
150 Ok((
151 <Self as Collate<A>>::collate(self, first)?,
152 <Self as Collate<B>>::collate(self, second)?,
153 ))
154 }
155}
156
157impl<A, B, C> Collate<(A, B, C)> for DefaultCollate
158where
159 A: Send + 'static,
160 B: Send + 'static,
161 C: Send + 'static,
162 DefaultCollate: Collate<A> + Collate<B> + Collate<C>,
163{
164 type Output = (
165 <DefaultCollate as Collate<A>>::Output,
166 <DefaultCollate as Collate<B>>::Output,
167 <DefaultCollate as Collate<C>>::Output,
168 );
169
170 fn collate(&self, batch: Vec<(A, B, C)>) -> BatchResult<Self::Output> {
171 let mut first = Vec::with_capacity(batch.len());
172 let mut second = Vec::with_capacity(batch.len());
173 let mut third = Vec::with_capacity(batch.len());
174 for (a, b, c) in batch {
175 first.push(a);
176 second.push(b);
177 third.push(c);
178 }
179 Ok((
180 <Self as Collate<A>>::collate(self, first)?,
181 <Self as Collate<B>>::collate(self, second)?,
182 <Self as Collate<C>>::collate(self, third)?,
183 ))
184 }
185}
186
187pub struct DataLoader<D, C = DefaultCollate>
189where
190 D: Dataset + 'static,
191 C: Collate<D::Item> + 'static,
192{
193 dataset: Arc<D>,
194 collate_fn: Arc<C>,
195 batch_size: usize,
196 num_workers: usize,
197 shuffle: bool,
198 drop_last: bool,
199 prefetch: NonZeroUsize,
200 seed: u64,
201 epoch: u64,
202 timeout: Option<Duration>,
203}
204
205pub struct DataLoaderBuilder<D, C>
207where
208 D: Dataset + 'static,
209 C: Collate<D::Item> + 'static,
210{
211 dataset: D,
212 collate_fn: C,
213 batch_size: usize,
214 workers: usize,
215 prefetch: usize,
216 drop_last: bool,
217 shuffle: bool,
218 seed: u64,
219 epoch: u64,
220 timeout: Option<Duration>,
221}
222
223impl<D, C> DataLoaderBuilder<D, C>
224where
225 D: Dataset + 'static,
226 C: Collate<D::Item> + 'static,
227{
228 pub fn batch_size(mut self, batch_size: usize) -> Self {
230 self.batch_size = batch_size;
231 self
232 }
233
234 #[must_use]
236 pub fn workers(mut self, workers: usize) -> Self {
237 self.workers = workers;
238 self
239 }
240
241 pub fn prefetch(mut self, prefetch: usize) -> Self {
243 self.prefetch = prefetch;
244 self
245 }
246
247 #[must_use]
249 pub fn drop_last(mut self, drop_last: bool) -> Self {
250 self.drop_last = drop_last;
251 self
252 }
253
254 #[must_use]
256 pub fn shuffle(mut self, shuffle: bool) -> Self {
257 self.shuffle = shuffle;
258 self
259 }
260
261 #[must_use]
263 pub fn seed(mut self, seed: u64) -> Self {
264 self.seed = seed;
265 self
266 }
267
268 #[must_use]
270 pub fn epoch(mut self, epoch: u64) -> Self {
271 self.epoch = epoch;
272 self
273 }
274
275 #[must_use]
277 pub fn timeout(mut self, timeout: Option<Duration>) -> Self {
278 self.timeout = timeout;
279 self
280 }
281
282 #[must_use = "building a loader returns the configured loader or its validation error"]
284 pub fn build(self) -> CoreResult<DataLoader<D, C>> {
285 let batch_size =
286 NonZeroUsize::new(self.batch_size).ok_or_else(|| Error::InvalidModuleState {
287 operation: "data_loader_builder",
288 reason: ErrorMessage::new("batch size must be non-zero"),
289 })?;
290 let prefetch =
291 NonZeroUsize::new(self.prefetch).ok_or_else(|| Error::InvalidModuleState {
292 operation: "data_loader_builder",
293 reason: ErrorMessage::new("prefetch capacity must be non-zero"),
294 })?;
295 Ok(DataLoader {
296 dataset: Arc::new(self.dataset),
297 collate_fn: Arc::new(self.collate_fn),
298 batch_size: batch_size.get(),
299 num_workers: self.workers,
300 shuffle: self.shuffle,
301 drop_last: self.drop_last,
302 prefetch,
303 seed: self.seed,
304 epoch: self.epoch,
305 timeout: self.timeout,
306 })
307 }
308}
309
310impl<D, C> DataLoader<D, C>
311where
312 D: Dataset + 'static,
313 C: Collate<D::Item> + 'static,
314{
315 pub fn new(dataset: D, collate_fn: C, batch_size: usize) -> CoreResult<Self> {
317 if batch_size == 0 {
318 return Err(Error::InvalidModuleState {
319 operation: "data_loader_new",
320 reason: ErrorMessage::new("batch size must be non-zero"),
321 });
322 }
323 Ok(Self {
324 dataset: Arc::new(dataset),
325 collate_fn: Arc::new(collate_fn),
326 batch_size,
327 num_workers: 0,
328 shuffle: false,
329 drop_last: false,
330 prefetch: NonZeroUsize::new(2).expect("constant is non-zero"),
331 seed: 0,
332 epoch: 0,
333 timeout: None,
334 })
335 }
336
337 #[must_use]
339 pub fn builder_with_collate(dataset: D, collate_fn: C) -> DataLoaderBuilder<D, C> {
340 DataLoaderBuilder {
341 dataset,
342 collate_fn,
343 batch_size: 1,
344 workers: 0,
345 prefetch: 2,
346 drop_last: false,
347 shuffle: false,
348 seed: 0,
349 epoch: 0,
350 timeout: None,
351 }
352 }
353
354 pub fn with_num_workers(mut self, num_workers: usize) -> Self {
356 self.num_workers = num_workers;
357 self
358 }
359
360 pub fn with_shuffle(mut self, shuffle: bool) -> Self {
362 self.shuffle = shuffle;
363 self
364 }
365
366 #[must_use]
368 pub fn with_drop_last(mut self, drop_last: bool) -> Self {
369 self.drop_last = drop_last;
370 self
371 }
372
373 #[must_use]
375 pub fn with_prefetch(mut self, prefetch: NonZeroUsize) -> Self {
376 self.prefetch = prefetch;
377 self
378 }
379
380 #[must_use]
382 pub fn with_seed(mut self, seed: u64) -> Self {
383 self.seed = seed;
384 self
385 }
386
387 #[must_use]
389 pub fn with_epoch(mut self, epoch: u64) -> Self {
390 self.epoch = epoch;
391 self
392 }
393
394 #[must_use]
396 pub fn with_timeout(mut self, timeout: Option<Duration>) -> Self {
397 self.timeout = timeout;
398 self
399 }
400}
401
402impl<D> DataLoader<D, DefaultCollate>
403where
404 D: Dataset + 'static,
405 D::Item: Send + 'static,
406 DefaultCollate: Collate<D::Item>,
407{
408 pub fn from_dataset(dataset: D, batch_size: usize) -> CoreResult<Self> {
411 Self::new(dataset, DefaultCollate, batch_size)
412 }
413
414 #[must_use]
416 pub fn default_builder(dataset: D) -> DataLoaderBuilder<D, DefaultCollate> {
417 Self::builder(dataset)
418 }
419
420 #[must_use]
422 pub fn builder(dataset: D) -> DataLoaderBuilder<D, DefaultCollate> {
423 DataLoaderBuilder {
424 dataset,
425 collate_fn: DefaultCollate,
426 batch_size: 1,
427 workers: 0,
428 prefetch: 2,
429 drop_last: false,
430 shuffle: false,
431 seed: 0,
432 epoch: 0,
433 timeout: None,
434 }
435 }
436}
437
438pub struct DataLoaderIter<T> {
440 sync_next: Option<Box<dyn FnMut() -> Option<BatchResult<T>> + Send>>,
441 receiver: Option<Receiver<(usize, BatchResult<T>)>>,
442 pending: BTreeMap<usize, BatchResult<T>>,
443 next_sequence: usize,
444 total_batches: usize,
445 terminated: bool,
446 timeout: Option<Duration>,
447 cancel: Arc<AtomicBool>,
448 workers: Vec<JoinHandle<()>>,
449}
450
451impl<T> Iterator for DataLoaderIter<T> {
452 type Item = BatchResult<T>;
454
455 fn next(&mut self) -> Option<Self::Item> {
457 if let Some(sync_next) = self.sync_next.as_mut() {
458 let batch = sync_next();
459 if batch.is_none() {
460 self.sync_next = None;
461 }
462 if batch.as_ref().is_some_and(|item| item.is_err()) {
463 self.terminated = true;
464 self.sync_next = None;
465 }
466 return batch;
467 }
468 if self.terminated || self.next_sequence >= self.total_batches {
469 return None;
470 }
471 if let Some(batch) = self.pending.remove(&self.next_sequence) {
472 self.next_sequence += 1;
473 if batch.is_err() {
474 self.terminated = true;
475 self.cancel.store(true, Ordering::Release);
476 self.receiver.take();
477 }
478 return Some(batch);
479 }
480 let receiver = self.receiver.as_ref()?;
481 loop {
482 let received = match self.timeout {
483 Some(duration) => receiver
484 .recv_timeout(duration)
485 .map_err(|error| match error {
486 std::sync::mpsc::RecvTimeoutError::Timeout => {
487 DataError::Timeout { duration }
488 }
489 std::sync::mpsc::RecvTimeoutError::Disconnected => {
490 DataError::WorkerDisconnected
491 }
492 }),
493 None => receiver.recv().map_err(|_| DataError::WorkerDisconnected),
494 };
495 match received {
496 Ok((sequence, batch)) if sequence == self.next_sequence => {
497 self.next_sequence += 1;
498 if batch.is_err() {
499 self.terminated = true;
500 self.cancel.store(true, Ordering::Release);
501 self.receiver.take();
502 }
503 return Some(batch);
504 }
505 Ok((sequence, batch)) => {
506 self.pending.insert(sequence, batch);
507 }
508 Err(error) => {
509 self.receiver = None;
510 self.terminated = true;
511 return Some(Err(error));
512 }
513 }
514 if let Some(batch) = self.pending.remove(&self.next_sequence) {
515 self.next_sequence += 1;
516 return Some(batch);
517 }
518 }
519 }
520}
521
522impl<T> Drop for DataLoaderIter<T> {
523 fn drop(&mut self) {
524 self.cancel.store(true, Ordering::Release);
525 self.sync_next.take();
526 self.receiver.take();
527 for worker in self.workers.drain(..) {
528 let _ = worker.join();
529 }
530 }
531}
532
533impl<D, C> IntoIterator for &DataLoader<D, C>
534where
535 D: Dataset + 'static,
536 C: Collate<D::Item> + 'static,
537{
538 type Item = BatchResult<C::Output>;
540 type IntoIter = DataLoaderIter<C::Output>;
542
543 fn into_iter(self) -> Self::IntoIter {
545 let mut indices: Vec<usize> = (0..self.dataset.len()).collect();
546 if self.shuffle {
547 let shuffle_seed = self
548 .seed
549 .wrapping_add(self.epoch.wrapping_mul(0x9E37_79B9_7F4A_7C15));
550 indices.shuffle(&mut StdRng::seed_from_u64(shuffle_seed));
551 }
552
553 let num_batches = if self.drop_last {
554 indices.len() / self.batch_size
555 } else {
556 indices.len().div_ceil(self.batch_size)
557 };
558 let mut batch_indices = Vec::with_capacity(num_batches);
559
560 for i in 0..num_batches {
561 let start = i * self.batch_size;
562 let end = core::cmp::min(start + self.batch_size, indices.len());
563 batch_indices.push(indices[start..end].to_vec());
564 }
565
566 let dataset = self.dataset.clone();
567 let collate_fn = self.collate_fn.clone();
568 let cancel = Arc::new(AtomicBool::new(false));
569 let mut workers = Vec::new();
570
571 if self.num_workers == 0 {
572 let mut batches = batch_indices.into_iter();
576 let sync_next = Box::new(move || {
577 let batch_idx = batches.next()?;
578 let mut batch = Vec::with_capacity(batch_idx.len());
579 for idx in batch_idx {
580 match dataset.get(idx) {
581 Ok(Some(item)) => batch.push(item),
582 Ok(None) => {
583 return Some(Err(DataError::IndexOutOfBounds {
584 index: idx,
585 len: dataset.len(),
586 }));
587 }
588 Err(error) => {
589 return Some(Err(error));
590 }
591 }
592 }
593 if !batch.is_empty() {
594 return Some(
595 catch_unwind(AssertUnwindSafe(|| collate_fn.collate(batch)))
596 .map_err(|_| DataError::CollatePanicked { worker_id: 0 })
597 .and_then(|result| result),
598 );
599 }
600 Some(Err(DataError::WorkerDisconnected))
601 });
602 DataLoaderIter {
603 sync_next: Some(sync_next),
604 receiver: None,
605 pending: BTreeMap::new(),
606 next_sequence: 0,
607 total_batches: num_batches,
608 terminated: false,
609 timeout: self.timeout,
610 cancel,
611 workers,
612 }
613 } else {
614 let (tx, rx) = sync_channel(self.prefetch.get());
616 let batch_indices = Arc::new(Mutex::new(batch_indices.into_iter().enumerate()));
617
618 for worker_id in 0..self.num_workers {
619 let dataset = dataset.clone();
620 let collate_fn = collate_fn.clone();
621 let tx = tx.clone();
622 let batch_indices = batch_indices.clone();
623 let cancel = cancel.clone();
624
625 workers.push(thread::spawn(move || {
626 loop {
627 if cancel.load(Ordering::Acquire) {
628 break;
629 }
630 let next_batch = {
631 let mut iter = batch_indices
636 .lock()
637 .unwrap_or_else(std::sync::PoisonError::into_inner);
638 iter.next()
639 };
640
641 if let Some((sequence, batch_idx)) = next_batch {
642 let mut batch = Vec::with_capacity(batch_idx.len());
643 for idx in batch_idx {
644 let result = catch_unwind(AssertUnwindSafe(|| dataset.get(idx)))
645 .map_err(|_| DataError::WorkerPanicked {
646 worker_id,
647 stage: "reading a sample",
648 })
649 .and_then(|result| result);
650 match result {
651 Ok(Some(item)) => batch.push(item),
652 Ok(None) => {
653 let _ = tx.send((
654 sequence,
655 Err(DataError::IndexOutOfBounds {
656 index: idx,
657 len: dataset.len(),
658 }),
659 ));
660 cancel.store(true, Ordering::Release);
661 return;
662 }
663 Err(error) => {
664 let _ = tx.send((sequence, Err(error)));
665 cancel.store(true, Ordering::Release);
666 return;
667 }
668 }
669 }
670 if !batch.is_empty() {
671 let collated =
672 catch_unwind(AssertUnwindSafe(|| collate_fn.collate(batch)))
673 .map_err(|_| DataError::CollatePanicked { worker_id })
674 .and_then(|result| result);
675 if tx.send((sequence, collated)).is_err() {
676 break;
677 }
678 }
679 } else {
680 break;
681 }
682 }
683 }));
684 }
685 drop(tx);
686 DataLoaderIter {
687 sync_next: None,
688 receiver: Some(rx),
689 pending: BTreeMap::new(),
690 next_sequence: 0,
691 total_batches: num_batches,
692 terminated: false,
693 timeout: self.timeout,
694 cancel,
695 workers,
696 }
697 }
698 }
699}
700
701#[cfg(test)]
702mod tests {
703 use super::*;
704 use std::collections::HashSet;
705 use std::time::Duration;
706
707 struct RangeDataset(usize);
709
710 impl Dataset for RangeDataset {
711 type Item = i32;
712 fn len(&self) -> usize {
713 self.0
714 }
715 fn get(&self, index: usize) -> BatchResult<Option<i32>> {
716 if index < self.0 {
717 Ok(Some(index as i32))
718 } else {
719 Ok(None)
720 }
721 }
722 }
723
724 struct VecCollate;
726 impl Collate<i32> for VecCollate {
727 type Output = Vec<i32>;
728 fn collate(&self, batch: Vec<i32>) -> BatchResult<Vec<i32>> {
729 Ok(batch)
730 }
731 }
732
733 struct CountingDataset {
734 reads: Arc<std::sync::atomic::AtomicUsize>,
735 len: usize,
736 }
737
738 impl Dataset for CountingDataset {
739 type Item = i32;
740
741 fn len(&self) -> usize {
742 self.len
743 }
744
745 fn get(&self, index: usize) -> BatchResult<Option<Self::Item>> {
746 self.reads.fetch_add(1, Ordering::Relaxed);
747 Ok((index < self.len).then_some(index as i32))
748 }
749 }
750
751 #[test]
752 fn zero_worker_iterator_fetches_only_the_next_batch() {
753 let reads = Arc::new(std::sync::atomic::AtomicUsize::new(0));
754 let loader = DataLoader::new(
755 CountingDataset {
756 reads: reads.clone(),
757 len: 9,
758 },
759 VecCollate,
760 3,
761 )
762 .unwrap();
763
764 let mut iter = (&loader).into_iter();
765 assert_eq!(reads.load(Ordering::Relaxed), 0);
766 assert_eq!(iter.next().unwrap().unwrap(), vec![0, 1, 2]);
767 assert_eq!(reads.load(Ordering::Relaxed), 3);
768 assert_eq!(iter.next().unwrap().unwrap(), vec![3, 4, 5]);
769 assert_eq!(reads.load(Ordering::Relaxed), 6);
770 }
771
772 #[test]
773 fn default_collation_returns_samples_without_custom_code() {
774 let loader = DataLoader::from_dataset(RangeDataset(5), 2).unwrap();
775 let batches = collect_with_timeout((&loader).into_iter());
776 assert_eq!(batches, vec![vec![0, 1], vec![2, 3], vec![4]]);
777 }
778
779 #[test]
780 fn default_collation_batches_tuple_fields() {
781 struct PairDataset;
782 impl Dataset for PairDataset {
783 type Item = (u32, u8);
784
785 fn len(&self) -> usize {
786 3
787 }
788
789 fn get(&self, index: usize) -> Result<Option<Self::Item>, DataError> {
790 Ok((index < 3).then_some((index as u32, index as u8)))
791 }
792 }
793
794 let loader = DataLoader::from_dataset(PairDataset, 2).unwrap();
795 let batches = collect_with_timeout((&loader).into_iter());
796 assert_eq!(batches, vec![(vec![0, 1], vec![0, 1]), (vec![2], vec![2])]);
797 }
798
799 #[test]
800 fn default_builder_keeps_loader_configuration_composable() {
801 let loader = DataLoader::default_builder(RangeDataset(4))
802 .batch_size(3)
803 .shuffle(true)
804 .seed(7)
805 .build()
806 .unwrap();
807 let batches = collect_with_timeout((&loader).into_iter());
808 assert_eq!(batches.iter().map(Vec::len).sum::<usize>(), 4);
809 }
810
811 fn collect_with_timeout<T>(
816 iter: impl Iterator<Item = BatchResult<T>> + Send + 'static,
817 ) -> Vec<T>
818 where
819 T: Send + 'static,
820 {
821 let (tx, rx) = std::sync::mpsc::channel();
822 std::thread::spawn(move || {
823 let _ = tx.send(iter.collect::<Result<Vec<T>, DataError>>());
824 });
825 rx.recv_timeout(Duration::from_secs(10))
826 .expect("DataLoader iteration did not finish within 10s (possible deadlock/hang)")
827 .expect("data loader returned an unexpected test error")
828 }
829
830 #[test]
831 fn single_threaded_yields_every_item_in_order_when_not_shuffled() {
832 let loader = DataLoader::new(RangeDataset(10), VecCollate, 3).unwrap();
833 let batches = collect_with_timeout((&loader).into_iter());
834
835 assert_eq!(
838 batches,
839 vec![vec![0, 1, 2], vec![3, 4, 5], vec![6, 7, 8], vec![9]]
840 );
841 }
842
843 #[test]
844 fn single_threaded_exact_division_produces_no_short_final_batch() {
845 let loader = DataLoader::new(RangeDataset(9), VecCollate, 3).unwrap();
846 let batches = collect_with_timeout((&loader).into_iter());
847 assert_eq!(batches, vec![vec![0, 1, 2], vec![3, 4, 5], vec![6, 7, 8]]);
848 }
849
850 #[test]
851 fn empty_dataset_produces_zero_batches() {
852 let loader = DataLoader::new(RangeDataset(0), VecCollate, 4).unwrap();
853 let batches = collect_with_timeout((&loader).into_iter());
854 assert!(batches.is_empty());
855 }
856
857 #[test]
858 fn zero_batch_size_is_a_typed_construction_error() {
859 let result = DataLoader::new(RangeDataset(4), VecCollate, 0);
860 assert!(matches!(
861 result,
862 Err(Error::InvalidModuleState {
863 operation: "data_loader_new",
864 ..
865 })
866 ));
867 }
868
869 #[test]
870 fn batch_size_larger_than_dataset_produces_one_short_batch() {
871 let loader = DataLoader::new(RangeDataset(3), VecCollate, 100).unwrap();
872 let batches = collect_with_timeout((&loader).into_iter());
873 assert_eq!(batches, vec![vec![0, 1, 2]]);
874 }
875
876 #[test]
877 fn shuffle_preserves_the_full_set_of_items_just_reorders_them() {
878 let loader = DataLoader::new(RangeDataset(50), VecCollate, 7)
879 .unwrap()
880 .with_shuffle(true);
881 let batches = collect_with_timeout((&loader).into_iter());
882
883 let all_items: HashSet<i32> = batches.iter().flatten().copied().collect();
884 assert_eq!(
885 all_items,
886 (0..50).collect::<HashSet<_>>(),
887 "shuffling must not drop or duplicate any item"
888 );
889 assert_eq!(batches.len(), 8);
891 }
892
893 #[test]
894 fn multi_worker_yields_every_item_exactly_once_no_duplicates_no_drops() {
895 let loader = DataLoader::new(RangeDataset(1000), VecCollate, 10)
903 .unwrap()
904 .with_num_workers(8);
905 let batches = collect_with_timeout((&loader).into_iter());
906
907 let mut all_items: Vec<i32> = batches.into_iter().flatten().collect();
908 assert_eq!(
909 all_items.len(),
910 1000,
911 "no item should be dropped or duplicated"
912 );
913 all_items.sort_unstable();
914 assert_eq!(all_items, (0..1000).collect::<Vec<i32>>());
915 }
916
917 #[test]
918 fn multi_worker_with_shuffle_still_covers_every_item_exactly_once() {
919 let loader = DataLoader::new(RangeDataset(500), VecCollate, 6)
920 .unwrap()
921 .with_num_workers(4)
922 .with_shuffle(true);
923 let batches = collect_with_timeout((&loader).into_iter());
924
925 let mut all_items: Vec<i32> = batches.into_iter().flatten().collect();
926 assert_eq!(all_items.len(), 500);
927 all_items.sort_unstable();
928 assert_eq!(all_items, (0..500).collect::<Vec<i32>>());
929 }
930
931 #[test]
932 fn more_workers_than_batches_does_not_hang_or_lose_items() {
933 let loader = DataLoader::new(RangeDataset(25), VecCollate, 10)
937 .unwrap()
938 .with_num_workers(8);
939 let batches = collect_with_timeout((&loader).into_iter());
940
941 let mut all_items: Vec<i32> = batches.into_iter().flatten().collect();
942 assert_eq!(all_items.len(), 25);
943 all_items.sort_unstable();
944 assert_eq!(all_items, (0..25).collect::<Vec<i32>>());
945 }
946
947 #[test]
948 fn collate_function_is_actually_invoked_per_batch() {
949 struct SumCollate;
953 impl Collate<i32> for SumCollate {
954 type Output = i32;
955 fn collate(&self, batch: Vec<i32>) -> BatchResult<i32> {
956 Ok(batch.into_iter().sum())
957 }
958 }
959
960 let loader = DataLoader::new(RangeDataset(6), SumCollate, 3).unwrap();
961 let mut sums = collect_with_timeout((&loader).into_iter());
962 sums.sort_unstable();
963 assert_eq!(sums, vec![3, 12]);
965 }
966
967 struct PanicDataset;
968 impl Dataset for PanicDataset {
969 type Item = i32;
970
971 fn len(&self) -> usize {
972 1
973 }
974
975 fn get(&self, _index: usize) -> BatchResult<Option<Self::Item>> {
976 panic!("fixture panic")
977 }
978 }
979
980 struct PanicCollate;
981 impl Collate<i32> for PanicCollate {
982 type Output = i32;
983
984 fn collate(&self, _batch: Vec<i32>) -> BatchResult<Self::Output> {
985 panic!("fixture panic")
986 }
987 }
988
989 #[test]
990 fn worker_panics_are_explicit_iterator_errors() {
991 let loader = DataLoader::new(PanicDataset, VecCollate, 1)
992 .unwrap()
993 .with_num_workers(2);
994 let error = (&loader).into_iter().next().unwrap().unwrap_err();
995 assert!(matches!(
996 error,
997 DataError::WorkerPanicked {
998 stage: "reading a sample",
999 ..
1000 }
1001 ));
1002 }
1003
1004 #[test]
1005 fn collate_panics_are_explicit_iterator_errors() {
1006 let loader = DataLoader::new(RangeDataset(1), PanicCollate, 1).unwrap();
1007 let error = (&loader).into_iter().next().unwrap().unwrap_err();
1008 assert!(matches!(error, DataError::CollatePanicked { worker_id: 0 }));
1009 }
1010
1011 struct FailingDataset;
1012 impl Dataset for FailingDataset {
1013 type Item = i32;
1014
1015 fn len(&self) -> usize {
1016 1
1017 }
1018
1019 fn get(&self, _index: usize) -> BatchResult<Option<Self::Item>> {
1020 Err(DataError::Dataset("fixture failure".into()))
1021 }
1022 }
1023
1024 #[test]
1025 fn dataset_errors_are_not_treated_as_end_of_data() {
1026 let loader = DataLoader::new(FailingDataset, VecCollate, 1).unwrap();
1027 assert!(matches!(
1028 (&loader).into_iter().next().unwrap(),
1029 Err(DataError::Dataset(message)) if message == "fixture failure"
1030 ));
1031 }
1032
1033 struct SlowDataset;
1034 impl Dataset for SlowDataset {
1035 type Item = i32;
1036
1037 fn len(&self) -> usize {
1038 1
1039 }
1040
1041 fn get(&self, _index: usize) -> BatchResult<Option<Self::Item>> {
1042 std::thread::sleep(Duration::from_millis(25));
1043 Ok(Some(1))
1044 }
1045 }
1046
1047 #[test]
1048 fn worker_timeout_is_an_explicit_iterator_error() {
1049 let loader = DataLoader::new(SlowDataset, VecCollate, 1)
1050 .unwrap()
1051 .with_num_workers(1)
1052 .with_timeout(Some(Duration::from_millis(1)));
1053 assert!(matches!(
1054 (&loader).into_iter().next().unwrap(),
1055 Err(DataError::Timeout { duration }) if duration == Duration::from_millis(1)
1056 ));
1057 }
1058
1059 #[test]
1060 fn builder_controls_drop_last_and_deterministic_shuffle() {
1061 let make = || {
1062 DataLoader::builder_with_collate(RangeDataset(10), VecCollate)
1063 .batch_size(3)
1064 .drop_last(true)
1065 .shuffle(true)
1066 .seed(17)
1067 .epoch(4)
1068 .prefetch(1)
1069 .build()
1070 .unwrap()
1071 };
1072 let first_loader = make();
1073 let second_loader = make();
1074 let first = collect_with_timeout((&first_loader).into_iter());
1075 let second = collect_with_timeout((&second_loader).into_iter());
1076 assert_eq!(first, second);
1077 assert_eq!(first.iter().map(Vec::len).sum::<usize>(), 9);
1078 }
1079}