Skip to main content

rusttorch_data/
lib.rs

1//! Typed datasets, samplers, batching, and loading for RustTorch.
2
3#![deny(missing_docs)]
4#![doc = include_str!("../COMPATIBILITY.md")]
5
6use std::{convert::Infallible, marker::PhantomData};
7
8use rusttorch_core::{Result, RustTorchError};
9
10mod checkpoint;
11mod collate;
12mod dataset;
13mod error;
14mod loader;
15mod memory;
16mod pin_memory;
17mod sampler;
18mod stream;
19mod transform;
20mod worker;
21mod worker_checkpoint;
22mod worker_context;
23
24pub use checkpoint::{
25    CheckpointActive, CheckpointBuildError, CheckpointDisabled, CheckpointFresh,
26    CheckpointIteration, CheckpointPinRequest, CheckpointPinStatus, CheckpointResume,
27    CheckpointSourceFactory, Checkpointable, CheckpointableSource, DatasetCheckpoint,
28    LOADER_STATE_SCHEMA_VERSION, LoaderConfiguration, LoaderState, ReplaySafeDataset, Stateless,
29    StatelessTransformFactory, StatelessWorker, StreamCheckpointBuildError,
30    StreamCheckpointConfiguration, StreamLaneState, StreamLoaderState, TransactionalCheckpoint,
31    TransactionalTransformFactory, TransactionalWorker, WorkerCheckpoint, WorkerCheckpointActive,
32    WorkerCheckpointIteration, WorkerLaneState, WorkerTransformLanes, WorkerTransformState,
33};
34pub use collate::{
35    Bytes, Collate, CollateError, DefaultCollate, DefaultCollator, DefaultConvert,
36    DefaultConverter, FnCollate, VecCollate,
37};
38pub use dataset::{
39    ConcatDataset, ReplaySafeMap, ReplaySafeTensorDataset, SplitLength, StackDataset, StackTuple,
40    Subset, TensorDataset, TransactionalMap, chain_datasets, random_split,
41};
42pub use error::{LoaderError, PipelineError};
43pub use loader::{
44    AutoBatch, BuilderDatasetMarker, CheckpointPlan, DataLoaderBuilder, ExplicitBatches,
45    LoaderIter, LoaderPlan, LoaderPlanConfiguration, NoBatch, OwnedDataLoader,
46    PlanCheckpointIdentity, SerialExecution, WorkerExecution, WorkerLoaderIter,
47};
48pub use memory::{MemoryDisabled, MemoryEnabled, MemoryFootprint};
49pub use pin_memory::{Auto, Explicit, PinDisabled, PinEnabled, PinMemory, PinMemoryStatus};
50pub use sampler::{
51    BatchSampler, BatchSamplerState, BatchSource, BatchSourceCheckpoint, DistributedConfiguration,
52    DistributedSampler, DistributedSamplerState, FnBatchSource, FnSampler, RandomReplacement,
53    RandomSampler, RandomSamplerState, Sampler, SamplerCheckpoint, SequentialSampler,
54    SequentialSamplerState, SubsetRandomSampler, SubsetRandomSamplerState, WeightedRandomSampler,
55    WeightedRandomSamplerState,
56};
57pub use stream::{
58    ExactStreamDataLoader, ExactStreamLoaderIter, LogicalSampleId, SequenceId, StreamDataLoader,
59    StreamDataLoaderBuilder, StreamLoaderIter, WorkerRecord, WorkerSourceFactory,
60};
61pub use transform::{
62    CloneTransformFactory, FnTransform, FnTransformFactory, IdentityTransform,
63    IdentityTransformFactory, TASK_RNG_DERIVATION_VERSION, TaskContext, Transform,
64    TransformFactory,
65};
66pub use worker_context::{
67    CancellationToken, Deadline, FnWorkerInit, LoaderCancelled, NoWorkerInit,
68    WORKER_SEED_DERIVATION_VERSION, WaitOutcome, WorkerContext, WorkerInfo, WorkerInit,
69    get_worker_info, with_worker_info,
70};
71
72/// A finite, indexable collection of samples.
73///
74/// Implementations return owned samples so loaders can move them into batches
75/// without cloning. Dataset-specific failures remain in [`Dataset::Error`].
76pub trait Dataset {
77    /// One owned item produced by the dataset.
78    type Sample;
79
80    /// An error returned while loading a sample.
81    type Error;
82
83    /// Returns the number of addressable samples.
84    fn len(&self) -> usize;
85
86    /// Loads the sample at `index`.
87    fn get(&self, index: usize) -> std::result::Result<Self::Sample, Self::Error>;
88
89    /// Loads samples for one index batch.
90    ///
91    /// The default calls [`Dataset::get`] once per index. Overrides must
92    /// return exactly one sample per supplied index and preserve index order.
93    fn get_batch(&self, indices: &[usize]) -> std::result::Result<Vec<Self::Sample>, Self::Error> {
94        indices.iter().map(|&index| self.get(index)).collect()
95    }
96
97    /// Loads one index batch with cooperative worker lifecycle context.
98    ///
99    /// The source-compatible default ignores `context` and delegates to
100    /// [`Dataset::get_batch`] exactly once. Context-aware datasets may
101    /// override this hook to honor cancellation and deadlines between bounded
102    /// operations. Rust cannot force-cancel an arbitrary blocking native call.
103    fn get_batch_with_context(
104        &self,
105        indices: &[usize],
106        context: &WorkerContext,
107    ) -> std::result::Result<Vec<Self::Sample>, Self::Error> {
108        let _ = context;
109        self.get_batch(indices)
110    }
111
112    /// Returns `true` when the dataset has no samples.
113    fn is_empty(&self) -> bool {
114        self.len() == 0
115    }
116
117    /// Iterates over every sample in index order.
118    ///
119    /// The iterator borrows the dataset and calls [`Dataset::get`] lazily.
120    fn samples(&self) -> DatasetSamples<'_, Self>
121    where
122        Self: Sized,
123    {
124        DatasetSamples {
125            dataset: self,
126            next_index: 0,
127        }
128    }
129}
130
131/// A borrowing, sequential iterator over a [`Dataset`].
132pub struct DatasetSamples<'a, D> {
133    dataset: &'a D,
134    next_index: usize,
135}
136
137impl<D> Iterator for DatasetSamples<'_, D>
138where
139    D: Dataset,
140{
141    type Item = std::result::Result<D::Sample, D::Error>;
142
143    fn next(&mut self) -> Option<Self::Item> {
144        if self.next_index >= self.dataset.len() {
145            return None;
146        }
147
148        let index = self.next_index;
149        self.next_index += 1;
150        Some(self.dataset.get(index))
151    }
152}
153
154type IdentityCollate<T, E> = fn(Vec<T>) -> std::result::Result<Vec<T>, E>;
155
156fn identity_batch<T, E>(samples: Vec<T>) -> std::result::Result<Vec<T>, E> {
157    Ok(samples)
158}
159
160struct DatasetBatchIterator<'a, D, S, C, B, E> {
161    dataset: &'a D,
162    sampler: S,
163    batch_size: usize,
164    drop_last: bool,
165    collate: C,
166    exhausted: bool,
167    output: PhantomData<fn() -> (B, E)>,
168}
169
170impl<D, S, C, B, E> Iterator for DatasetBatchIterator<'_, D, S, C, B, E>
171where
172    D: Dataset,
173    S: Iterator<Item = usize>,
174    C: FnMut(Vec<D::Sample>) -> std::result::Result<B, E>,
175    E: From<D::Error>,
176{
177    type Item = std::result::Result<B, E>;
178
179    fn next(&mut self) -> Option<Self::Item> {
180        if self.exhausted {
181            return None;
182        }
183
184        let mut indices = Vec::with_capacity(self.batch_size);
185        while indices.len() < self.batch_size {
186            match self.sampler.next() {
187                Some(index) => indices.push(index),
188                None => {
189                    self.exhausted = true;
190                    if indices.is_empty() {
191                        return None;
192                    }
193                    break;
194                }
195            }
196        }
197
198        let samples = match self.dataset.get_batch(&indices) {
199            Ok(samples) => samples,
200            Err(error) => {
201                self.exhausted = true;
202                return Some(Err(E::from(error)));
203            }
204        };
205        assert_eq!(
206            samples.len(),
207            indices.len(),
208            "Dataset::get_batch returned {} samples for {} indices",
209            samples.len(),
210            indices.len()
211        );
212        if self.drop_last && indices.len() < self.batch_size {
213            return None;
214        }
215        let batch = (self.collate)(samples);
216        if batch.is_err() {
217            self.exhausted = true;
218        }
219        Some(batch)
220    }
221}
222
223struct BatchIterator<I, C, T, B, E> {
224    source: I,
225    batch_size: usize,
226    drop_last: bool,
227    collate: C,
228    exhausted: bool,
229    output: PhantomData<fn(T) -> (B, E)>,
230}
231
232impl<I, C, T, B, E> BatchIterator<I, C, T, B, E> {
233    fn new(source: I, batch_size: usize, drop_last: bool, collate: C) -> Result<Self> {
234        if batch_size == 0 {
235            return Err(RustTorchError::InvalidConfiguration {
236                field: "batch_size",
237                reason: "must be greater than zero".to_owned(),
238            });
239        }
240
241        Ok(Self {
242            source,
243            batch_size,
244            drop_last,
245            collate,
246            exhausted: false,
247            output: PhantomData,
248        })
249    }
250}
251
252impl<I, C, T, B, E> Iterator for BatchIterator<I, C, T, B, E>
253where
254    I: Iterator<Item = std::result::Result<T, E>>,
255    C: FnMut(Vec<T>) -> std::result::Result<B, E>,
256{
257    type Item = std::result::Result<B, E>;
258
259    fn next(&mut self) -> Option<Self::Item> {
260        if self.exhausted {
261            return None;
262        }
263
264        let first = match self.source.next() {
265            Some(Ok(sample)) => sample,
266            Some(Err(error)) => {
267                self.exhausted = true;
268                return Some(Err(error));
269            }
270            None => {
271                self.exhausted = true;
272                return None;
273            }
274        };
275
276        let mut samples = Vec::with_capacity(self.batch_size);
277        samples.push(first);
278        while samples.len() < self.batch_size {
279            match self.source.next() {
280                Some(Ok(sample)) => samples.push(sample),
281                Some(Err(error)) => {
282                    self.exhausted = true;
283                    return Some(Err(error));
284                }
285                None => {
286                    self.exhausted = true;
287                    if self.drop_last {
288                        return None;
289                    }
290                    break;
291                }
292            }
293        }
294
295        let batch = (self.collate)(samples);
296        if batch.is_err() {
297            self.exhausted = true;
298        }
299        Some(batch)
300    }
301}
302
303/// Batches an ordinary fallible sample iterator into vectors.
304///
305/// Samples are moved into one pre-sized vector per batch. A short final batch
306/// is omitted when `drop_last` is `true`. Source errors are yielded once and
307/// then terminate the returned iterator.
308///
309/// # Errors
310///
311/// Returns [`RustTorchError::InvalidConfiguration`] when `batch_size` is zero.
312///
313/// # Examples
314///
315/// An ordinary fallible iterator is enough for streaming data:
316///
317/// ```
318/// use rusttorch_data::batches;
319///
320/// let records = ["10", "20", "30"].into_iter().map(str::parse::<i64>);
321/// let loader = batches(records, 2, false).expect("batch size is nonzero");
322/// let batches = loader
323///     .collect::<Result<Vec<_>, _>>()
324///     .expect("every record is an integer");
325///
326/// assert_eq!(batches, vec![vec![10, 20], vec![30]]);
327/// ```
328pub fn batches<I, T, E>(
329    source: I,
330    batch_size: usize,
331    drop_last: bool,
332) -> Result<impl Iterator<Item = std::result::Result<Vec<T>, E>>>
333where
334    I: Iterator<Item = std::result::Result<T, E>>,
335{
336    batches_with_collate(source, batch_size, drop_last, identity_batch::<T, E>)
337}
338
339/// Batches an ordinary fallible sample iterator with custom collation.
340///
341/// The closure receives ownership of exactly one vector of samples and may
342/// return any batch type. A short final batch is omitted when `drop_last` is
343/// `true`. Source and collation errors are yielded once and then terminate the
344/// returned iterator.
345///
346/// # Errors
347///
348/// Returns [`RustTorchError::InvalidConfiguration`] when `batch_size` is zero.
349pub fn batches_with_collate<I, C, T, B, E>(
350    source: I,
351    batch_size: usize,
352    drop_last: bool,
353    collate: C,
354) -> Result<impl Iterator<Item = std::result::Result<B, E>>>
355where
356    I: Iterator<Item = std::result::Result<T, E>>,
357    C: FnMut(Vec<T>) -> std::result::Result<B, E>,
358{
359    BatchIterator::new(source, batch_size, drop_last, collate)
360}
361
362/// A single-threaded iterator over batches from a map-style [`Dataset`].
363///
364/// The loader borrows its dataset and owns both its sampler and collation
365/// closure. Samples are moved into one pre-sized vector per batch without a
366/// `Clone` requirement. Dataset and collation errors are yielded once and
367/// then terminate the iterator.
368///
369/// # Examples
370///
371/// A seeded sampler and a collation closure can produce tensor batches:
372///
373/// ```no_run
374/// use std::convert::Infallible;
375///
376/// use rusttorch_core::{Result, Tensor};
377/// use rusttorch_data::{DataLoader, Dataset, RandomSampler};
378///
379/// struct Rows(usize);
380///
381/// impl Dataset for Rows {
382///     type Sample = Tensor;
383///     type Error = Infallible;
384///
385///     fn len(&self) -> usize {
386///         self.0
387///     }
388///
389///     fn get(&self, index: usize) -> std::result::Result<Tensor, Infallible> {
390///         Ok(Tensor::from_slice(&[index as f32]))
391///     }
392/// }
393///
394/// fn main() -> Result<()> {
395///     let dataset = Rows(8);
396///     let sampler = RandomSampler::new(dataset.len(), 42)?;
397///     let loader = DataLoader::with_collate(
398///         &dataset,
399///         sampler,
400///         4,
401///         false,
402///         |samples| Ok::<_, Infallible>(Tensor::stack(&samples, 0)),
403///     )?;
404///
405///     for batch in loader {
406///         let tensor = batch.expect("dataset and collation are infallible");
407///         assert_eq!(tensor.size(), [4, 1]);
408///     }
409///     Ok(())
410/// }
411/// ```
412pub struct DataLoader<
413    'a,
414    D = BuilderDatasetMarker,
415    S = std::iter::Empty<usize>,
416    C = (),
417    B = (),
418    E = Infallible,
419> where
420    D: Dataset,
421{
422    batches: DatasetBatchIterator<'a, D, S, C, B, E>,
423}
424
425impl DataLoader<'static, BuilderDatasetMarker, std::iter::Empty<usize>, (), (), Infallible> {
426    /// Starts an owned, re-iterable loader builder for `dataset`.
427    ///
428    /// ```no_run
429    /// use std::convert::Infallible;
430    /// use rusttorch_core::Result;
431    /// use rusttorch_data::{DataLoader, Dataset, VecCollate};
432    ///
433    /// struct Rows(Vec<i64>);
434    ///
435    /// impl Dataset for Rows {
436    ///     type Sample = i64;
437    ///     type Error = Infallible;
438    ///
439    ///     fn len(&self) -> usize { self.0.len() }
440    ///     fn get(&self, index: usize) -> std::result::Result<i64, Infallible> {
441    ///         Ok(self.0[index])
442    ///     }
443    /// }
444    ///
445    /// fn main() -> Result<()> {
446    ///     let mut loader = DataLoader::builder(Rows(vec![1, 2, 3]))
447    ///         .batch_size(2)
448    ///         .collate(VecCollate)
449    ///         .build()?;
450    ///     let batches = loader.iter().collect::<std::result::Result<Vec<_>, _>>()
451    ///         .expect("the dataset and VecCollate are infallible");
452    ///     assert_eq!(batches, [vec![1, 2], vec![3]]);
453    ///     Ok(())
454    /// }
455    /// ```
456    pub fn builder<D>(
457        dataset: D,
458    ) -> DataLoaderBuilder<D, AutoBatch<SequentialSampler>, DefaultCollator>
459    where
460        D: Dataset,
461    {
462        DataLoaderBuilder::new(dataset)
463    }
464}
465
466impl<'a, D, S> DataLoader<'a, D, S, IdentityCollate<D::Sample, D::Error>, Vec<D::Sample>, D::Error>
467where
468    D: Dataset,
469    S: Iterator<Item = usize>,
470{
471    /// Creates a loader whose batches are vectors of owned samples.
472    ///
473    /// `dataset` is borrowed, while `sampler` is consumed by the loader.
474    /// A short final batch is omitted when `drop_last` is `true`.
475    ///
476    /// # Errors
477    ///
478    /// Returns [`RustTorchError::InvalidConfiguration`] when `batch_size` is
479    /// zero.
480    pub fn new(dataset: &'a D, sampler: S, batch_size: usize, drop_last: bool) -> Result<Self> {
481        Self::with_collate(
482            dataset,
483            sampler,
484            batch_size,
485            drop_last,
486            identity_batch::<D::Sample, D::Error>,
487        )
488    }
489}
490
491impl<'a, D, S, C, B, E> DataLoader<'a, D, S, C, B, E>
492where
493    D: Dataset,
494    S: Iterator<Item = usize>,
495    C: FnMut(Vec<D::Sample>) -> std::result::Result<B, E>,
496    E: From<D::Error>,
497{
498    /// Creates a loader with fallible custom collation.
499    ///
500    /// The closure receives ownership of exactly one vector of samples and
501    /// may return any batch type. Dataset failures are converted into the
502    /// closure's error type through [`From`]. A short final batch is omitted
503    /// when `drop_last` is `true`.
504    ///
505    /// # Errors
506    ///
507    /// Returns [`RustTorchError::InvalidConfiguration`] when `batch_size` is
508    /// zero. Dataset and collation failures are returned by iteration.
509    pub fn with_collate(
510        dataset: &'a D,
511        sampler: S,
512        batch_size: usize,
513        drop_last: bool,
514        collate: C,
515    ) -> Result<Self> {
516        if batch_size == 0 {
517            return Err(RustTorchError::InvalidConfiguration {
518                field: "batch_size",
519                reason: "must be greater than zero".to_owned(),
520            });
521        }
522        Ok(Self {
523            batches: DatasetBatchIterator {
524                dataset,
525                sampler,
526                batch_size,
527                drop_last,
528                collate,
529                exhausted: false,
530                output: PhantomData,
531            },
532        })
533    }
534}
535
536impl<D, S, C, B, E> Iterator for DataLoader<'_, D, S, C, B, E>
537where
538    D: Dataset,
539    S: Iterator<Item = usize>,
540    C: FnMut(Vec<D::Sample>) -> std::result::Result<B, E>,
541    E: From<D::Error>,
542{
543    type Item = std::result::Result<B, E>;
544
545    fn next(&mut self) -> Option<Self::Item> {
546        self.batches.next()
547    }
548}