Skip to main content

incin_data/
loader.rs

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/// A recoverable data-pipeline failure.
24///
25/// This is the crate's typed error: iteration, collation, and transform
26/// failures return it instead of an untyped stringly error, so callers can
27/// match on the failure category rather than parse text.
28#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
29pub enum DataError {
30    /// The dataset reported malformed or otherwise invalid data.
31    #[error("dataset error: {0}")]
32    Dataset(String),
33    /// A requested index was outside the dataset's declared range.
34    #[error("dataset index {index} is outside length {len}")]
35    IndexOutOfBounds {
36        /// The rejected index.
37        index: usize,
38        /// The dataset length it was checked against.
39        len: usize,
40    },
41    /// A worker caught a panic while reading a sample.
42    #[error("worker {worker_id} panicked while {stage}")]
43    WorkerPanicked {
44        /// The worker that observed the panic.
45        worker_id: usize,
46        /// The pipeline stage the worker was running.
47        stage: &'static str,
48    },
49    /// A worker caught a panic while collating a batch.
50    #[error("worker {worker_id} panicked while collating")]
51    CollatePanicked {
52        /// The worker that observed the panic.
53        worker_id: usize,
54    },
55    /// The samples could not be combined into a batch.
56    #[error("invalid batch: {0}")]
57    InvalidBatch(String),
58    /// A worker stopped unexpectedly before completing the epoch.
59    #[error("data-loader worker disconnected")]
60    WorkerDisconnected,
61    /// The configured worker receive timeout elapsed.
62    #[error("data-loader timed out after {duration:?}")]
63    Timeout {
64        /// The timeout that elapsed.
65        duration: Duration,
66    },
67    /// A transform or caller-supplied input violated its declared contract.
68    #[error("invalid input: {0}")]
69    InvalidInput(String),
70}
71
72/// A batch result returned by [`DataLoaderIter`].
73pub type BatchResult<T> = core::result::Result<T, DataError>;
74
75/// Collate.
76pub trait Collate<T>: Send + Sync {
77    /// Output.
78    type Output: Send + 'static;
79    /// Collate.
80    fn collate(&self, batch: Vec<T>) -> BatchResult<Self::Output>;
81}
82
83/// The default collation policy for common scalar, tuple, and tensor samples.
84#[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
187/// Data loader.
188pub 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
205/// Configures a [`DataLoader`] before construction.
206pub 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    /// Sets the batch size.
229    pub fn batch_size(mut self, batch_size: usize) -> Self {
230        self.batch_size = batch_size;
231        self
232    }
233
234    /// Sets the number of worker threads.
235    #[must_use]
236    pub fn workers(mut self, workers: usize) -> Self {
237        self.workers = workers;
238        self
239    }
240
241    /// Sets the bounded worker prefetch capacity.
242    pub fn prefetch(mut self, prefetch: usize) -> Self {
243        self.prefetch = prefetch;
244        self
245    }
246
247    /// Drops the final incomplete batch when enabled.
248    #[must_use]
249    pub fn drop_last(mut self, drop_last: bool) -> Self {
250        self.drop_last = drop_last;
251        self
252    }
253
254    /// Enables or disables deterministic shuffling.
255    #[must_use]
256    pub fn shuffle(mut self, shuffle: bool) -> Self {
257        self.shuffle = shuffle;
258        self
259    }
260
261    /// Sets the deterministic shuffle seed.
262    #[must_use]
263    pub fn seed(mut self, seed: u64) -> Self {
264        self.seed = seed;
265        self
266    }
267
268    /// Sets the epoch used in deterministic seed derivation.
269    #[must_use]
270    pub fn epoch(mut self, epoch: u64) -> Self {
271        self.epoch = epoch;
272        self
273    }
274
275    /// Sets an explicit worker receive timeout.
276    #[must_use]
277    pub fn timeout(mut self, timeout: Option<Duration>) -> Self {
278        self.timeout = timeout;
279        self
280    }
281
282    /// Builds the configured loader.
283    #[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    /// New.
316    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    /// Starts a builder with a default batch size of one.
338    #[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    /// With num workers.
355    pub fn with_num_workers(mut self, num_workers: usize) -> Self {
356        self.num_workers = num_workers;
357        self
358    }
359
360    /// With shuffle.
361    pub fn with_shuffle(mut self, shuffle: bool) -> Self {
362        self.shuffle = shuffle;
363        self
364    }
365
366    /// Drops the final incomplete batch when enabled.
367    #[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    /// Sets bounded worker prefetch capacity.
374    #[must_use]
375    pub fn with_prefetch(mut self, prefetch: NonZeroUsize) -> Self {
376        self.prefetch = prefetch;
377        self
378    }
379
380    /// Sets deterministic shuffle seed.
381    #[must_use]
382    pub fn with_seed(mut self, seed: u64) -> Self {
383        self.seed = seed;
384        self
385    }
386
387    /// Sets the deterministic epoch number.
388    #[must_use]
389    pub fn with_epoch(mut self, epoch: u64) -> Self {
390        self.epoch = epoch;
391        self
392    }
393
394    /// Sets an explicit worker receive timeout.
395    #[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    /// Creates a loader using [`DefaultCollate`] for scalar, tuple, and tensor
409    /// batches.
410    pub fn from_dataset(dataset: D, batch_size: usize) -> CoreResult<Self> {
411        Self::new(dataset, DefaultCollate, batch_size)
412    }
413
414    /// Starts a builder using [`DefaultCollate`].
415    #[must_use]
416    pub fn default_builder(dataset: D) -> DataLoaderBuilder<D, DefaultCollate> {
417        Self::builder(dataset)
418    }
419
420    /// Starts a builder using [`DefaultCollate`].
421    #[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
438/// Data loader iter.
439pub 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    /// Item.
453    type Item = BatchResult<T>;
454
455    /// Next.
456    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    /// Item.
539    type Item = BatchResult<C::Output>;
540    /// Into iter.
541    type IntoIter = DataLoaderIter<C::Output>;
542
543    /// Into iter.
544    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            // Keep the synchronous path lazy: constructing the iterator only
573            // prepares indices. Dataset access and collation happen in the
574            // caller's `next()` call, one batch at a time.
575            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            // Multi-threaded
615            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                            // The lock only protects `Iterator::next`; user
632                            // dataset/collate code runs after it is released.
633                            // Recover the iterator if a worker was aborted
634                            // rather than turning mutex poison into a panic.
635                            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    /// A trivial in-memory dataset of `i32`s, `0..len`.
708    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    /// Collates a batch by just returning it as-is (`Vec<i32>`).
725    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    // Every test below has a hard wall-clock timeout: a regression in the
812    // worker-thread loop (e.g. a channel deadlock, an off-by-one in
813    // `batch_indices` that spins forever) must fail loudly and quickly
814    // instead of hanging the test suite indefinitely.
815    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        // 10 items / batch_size 3 -> batches of [3,3,3,1], nothing dropped,
836        // nothing duplicated, original order preserved (no shuffle).
837        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        // 50 / 7 = 7 batches of 7 plus one short batch of 1.
890        assert_eq!(batches.len(), 8);
891    }
892
893    #[test]
894    fn multi_worker_yields_every_item_exactly_once_no_duplicates_no_drops() {
895        // Regression guard for the DataLoader's core concurrency invariant:
896        // multiple worker threads pull batch-index chunks from a single
897        // Mutex<Iterator> (loader.rs's `batch_indices`) and push collated
898        // batches through a shared bounded mpsc channel. A bug here (e.g. two
899        // workers racing on the same chunk, or one silently starving) would
900        // show up as a missing or duplicated item, which is exactly the kind
901        // of concurrency bug that's invisible without a real multi-thread run.
902        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        // Edge case: 3 batches total but 8 workers requested. Workers that
934        // find the shared iterator already exhausted must exit cleanly
935        // instead of spinning or blocking the others.
936        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        // A Collate impl that transforms the batch (sums it) rather than
950        // passing it through unchanged, proving collate_fn is really called
951        // (not bypassed).
952        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        // batch [0,1,2] -> 3, batch [3,4,5] -> 12
964        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}