Skip to main content

rusttorch_data/
error.rs

1use rusttorch_core::RustTorchError;
2
3/// A preserved failure from one typed data-pipeline stage.
4#[derive(Debug, thiserror::Error)]
5#[non_exhaustive]
6pub enum PipelineError<DE, TE, CE, FE, IE> {
7    /// Explicit streaming source creation or iteration failed.
8    #[error("stream source failed: {0}")]
9    Source(#[source] DE),
10    /// Dataset fetch failed.
11    #[error("dataset fetch failed: {0}")]
12    Dataset(#[source] DE),
13    /// Sample transformation failed.
14    #[error("transform failed: {0}")]
15    Transform(#[source] TE),
16    /// Coordinator collation failed.
17    #[error("collation failed: {0}")]
18    Collate(#[source] CE),
19    /// Per-iterator or per-worker transform construction failed.
20    #[error("transform initialization failed: {0}")]
21    TransformInit(#[source] FE),
22    /// Worker initialization failed.
23    #[error("worker initialization failed: {0}")]
24    WorkerInit(#[source] IE),
25}
26
27/// A typed failure produced while an owned data loader is active.
28#[derive(Debug, thiserror::Error)]
29#[non_exhaustive]
30pub enum LoaderError<E> {
31    /// A dataset, transform, or collation stage failed.
32    #[error("data pipeline failed (batch {batch:?}, worker {worker:?}): {source}")]
33    Pipeline {
34        /// Logical batch when known.
35        batch: Option<u64>,
36        /// Worker identifier, or `None` for coordinator work.
37        worker: Option<usize>,
38        /// Preserved pipeline error.
39        #[source]
40        source: E,
41    },
42    /// An explicitly sharded stream stage failed.
43    #[error(
44        "stream pipeline failed (batch {batch:?}, worker {worker}, sequence {sequence:?}, logical sample {logical_id:?}): {source}"
45    )]
46    StreamPipeline {
47        /// Logical batch when known.
48        batch: Option<u64>,
49        /// Worker identifier.
50        worker: usize,
51        /// Stream sequence when known.
52        sequence: Option<u64>,
53        /// Stable logical sample identifier when known.
54        logical_id: Option<u64>,
55        /// Preserved pipeline error.
56        #[source]
57        source: E,
58    },
59    /// A worker thread panicked.
60    #[error("worker {worker} panicked while loading batch {batch:?}")]
61    WorkerPanic {
62        /// Worker identifier.
63        worker: usize,
64        /// Logical batch when known.
65        batch: Option<u64>,
66    },
67    /// An explicitly sharded stream worker panicked.
68    #[error(
69        "stream worker {worker} panicked (batch {batch:?}, sequence {sequence:?}, logical sample {logical_id:?})"
70    )]
71    StreamWorkerPanic {
72        /// Worker identifier.
73        worker: usize,
74        /// Logical batch when known.
75        batch: Option<u64>,
76        /// Stream sequence when known.
77        sequence: Option<u64>,
78        /// Stable logical sample identifier when known.
79        logical_id: Option<u64>,
80    },
81    /// Coordinator-owned user code panicked.
82    #[error("coordinator {stage} panicked (batch {batch:?})")]
83    CoordinatorPanic {
84        /// User-code stage that panicked.
85        stage: &'static str,
86        /// Logical batch when known.
87        batch: Option<u64>,
88    },
89    /// Waiting for a batch exceeded the configured timeout.
90    #[error("timed out waiting for batch {batch}")]
91    Timeout {
92        /// Logical batch being awaited.
93        batch: u64,
94    },
95    /// Loading was cancelled.
96    #[error("loader was cancelled")]
97    Cancelled,
98    /// A loader channel closed before the expected batch arrived.
99    #[error("loader channel closed before batch {batch}")]
100    ChannelClosed {
101        /// Logical batch being awaited.
102        batch: u64,
103    },
104    /// Batched dataset fetch returned the wrong number of samples.
105    #[error(
106        "batch {batch} on worker {worker:?} requested {expected} samples but the dataset returned {actual}"
107    )]
108    InvalidBatchCardinality {
109        /// Logical batch that failed.
110        batch: u64,
111        /// Worker identifier, or `None` for serial loading.
112        worker: Option<usize>,
113        /// Number of requested samples.
114        expected: usize,
115        /// Number of returned samples.
116        actual: usize,
117    },
118    /// A streaming source violated its sequence protocol.
119    #[error("stream protocol failed at sequence {sequence:?}: {reason}")]
120    StreamProtocol {
121        /// Sequence identifier when known.
122        sequence: Option<u64>,
123        /// Human-readable protocol violation.
124        reason: String,
125    },
126    /// A sample or batch exceeded the configured byte budget.
127    #[error(
128        "prefetch item exceeded the {limit} byte budget with {actual} bytes (batch {batch:?}, worker {worker:?}, sequence {sequence:?}, logical sample {logical_id:?})"
129    )]
130    MemoryLimit {
131        /// Logical batch when known.
132        batch: Option<u64>,
133        /// Worker identifier when known.
134        worker: Option<usize>,
135        /// Stream sequence when known.
136        sequence: Option<u64>,
137        /// Logical sample identifier when known.
138        logical_id: Option<u64>,
139        /// Configured byte limit.
140        limit: usize,
141        /// Actual byte footprint.
142        actual: usize,
143    },
144    /// Pinning a completed batch failed.
145    #[error("pinning batch {batch} failed: {source}")]
146    PinMemory {
147        /// Logical batch that failed.
148        batch: u64,
149        /// Preserved backend failure.
150        #[source]
151        source: RustTorchError,
152    },
153    /// Checkpoint state was unavailable, corrupt, or incompatible.
154    #[error("checkpoint is incompatible or unavailable: {reason}")]
155    Checkpoint {
156        /// Human-readable checkpoint rejection.
157        reason: String,
158    },
159    /// Loader configuration is invalid or temporarily unsupported.
160    #[error(transparent)]
161    Configuration(#[from] RustTorchError),
162}