qubit_progress/model/progress_event.rs
1/*******************************************************************************
2 *
3 * Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10use std::time::Duration;
11
12use super::{
13 ProgressCounters,
14 ProgressEventBuilder,
15 ProgressPhase,
16 ProgressStage,
17};
18
19/// Immutable progress event delivered to reporters.
20#[derive(Debug, Clone, PartialEq)]
21pub struct ProgressEvent {
22 /// Lifecycle phase of the reported operation.
23 phase: ProgressPhase,
24 /// Optional current stage.
25 stage: Option<ProgressStage>,
26 /// Generic counters for the operation.
27 counters: ProgressCounters,
28 /// Monotonic elapsed duration.
29 elapsed: Duration,
30}
31
32impl ProgressEvent {
33 /// Creates a progress event builder.
34 ///
35 /// # Returns
36 ///
37 /// A builder initialized as running, unknown-total progress with zeroed
38 /// counters and zero elapsed time.
39 #[inline]
40 pub const fn builder() -> ProgressEventBuilder {
41 ProgressEventBuilder::new()
42 }
43
44 /// Creates a progress event.
45 ///
46 /// # Parameters
47 ///
48 /// * `builder` - Builder containing configured event fields.
49 ///
50 /// # Returns
51 ///
52 /// A progress event built from `builder`.
53 #[inline]
54 pub fn new(builder: ProgressEventBuilder) -> Self {
55 Self {
56 phase: builder.phase,
57 stage: builder.stage,
58 counters: builder.counters,
59 elapsed: builder.elapsed,
60 }
61 }
62
63 /// Creates a started progress event.
64 ///
65 /// # Parameters
66 ///
67 /// * `counters` - Initial progress counters.
68 /// * `elapsed` - Elapsed duration at start, usually zero.
69 ///
70 /// # Returns
71 ///
72 /// A progress event with [`ProgressPhase::Started`].
73 #[inline]
74 pub const fn started(counters: ProgressCounters, elapsed: Duration) -> Self {
75 Self {
76 phase: ProgressPhase::Started,
77 stage: None,
78 counters,
79 elapsed,
80 }
81 }
82
83 /// Creates a running progress event.
84 ///
85 /// # Parameters
86 ///
87 /// * `counters` - Current progress counters.
88 /// * `elapsed` - Elapsed duration since operation start.
89 ///
90 /// # Returns
91 ///
92 /// A progress event with [`ProgressPhase::Running`].
93 #[inline]
94 pub const fn running(counters: ProgressCounters, elapsed: Duration) -> Self {
95 Self {
96 phase: ProgressPhase::Running,
97 stage: None,
98 counters,
99 elapsed,
100 }
101 }
102
103 /// Creates a finished progress event.
104 ///
105 /// # Parameters
106 ///
107 /// * `counters` - Final progress counters.
108 /// * `elapsed` - Total elapsed duration.
109 ///
110 /// # Returns
111 ///
112 /// A progress event with [`ProgressPhase::Finished`].
113 #[inline]
114 pub const fn finished(counters: ProgressCounters, elapsed: Duration) -> Self {
115 Self {
116 phase: ProgressPhase::Finished,
117 stage: None,
118 counters,
119 elapsed,
120 }
121 }
122
123 /// Creates a failed progress event.
124 ///
125 /// # Parameters
126 ///
127 /// * `counters` - Final or current progress counters.
128 /// * `elapsed` - Elapsed duration at failure.
129 ///
130 /// # Returns
131 ///
132 /// A progress event with [`ProgressPhase::Failed`].
133 #[inline]
134 pub const fn failed(counters: ProgressCounters, elapsed: Duration) -> Self {
135 Self {
136 phase: ProgressPhase::Failed,
137 stage: None,
138 counters,
139 elapsed,
140 }
141 }
142
143 /// Creates a canceled progress event.
144 ///
145 /// # Parameters
146 ///
147 /// * `counters` - Final or current progress counters.
148 /// * `elapsed` - Elapsed duration at cancellation.
149 ///
150 /// # Returns
151 ///
152 /// A progress event with [`ProgressPhase::Canceled`].
153 #[inline]
154 pub const fn canceled(counters: ProgressCounters, elapsed: Duration) -> Self {
155 Self {
156 phase: ProgressPhase::Canceled,
157 stage: None,
158 counters,
159 elapsed,
160 }
161 }
162
163 /// Creates a progress event for the supplied lifecycle phase.
164 ///
165 /// # Parameters
166 ///
167 /// * `phase` - Lifecycle phase for the event.
168 /// * `counters` - Progress counters carried by the event.
169 /// * `elapsed` - Elapsed duration carried by the event.
170 ///
171 /// # Returns
172 ///
173 /// A progress event with `phase`, `counters`, and `elapsed`.
174 #[inline]
175 pub const fn from_phase(
176 phase: ProgressPhase,
177 counters: ProgressCounters,
178 elapsed: Duration,
179 ) -> Self {
180 match phase {
181 ProgressPhase::Started => Self::started(counters, elapsed),
182 ProgressPhase::Running => Self::running(counters, elapsed),
183 ProgressPhase::Finished => Self::finished(counters, elapsed),
184 ProgressPhase::Failed => Self::failed(counters, elapsed),
185 ProgressPhase::Canceled => Self::canceled(counters, elapsed),
186 }
187 }
188
189 /// Returns a copy configured with the current stage.
190 ///
191 /// # Parameters
192 ///
193 /// * `stage` - Current operation stage.
194 ///
195 /// # Returns
196 ///
197 /// This event with `stage` recorded.
198 #[inline]
199 pub fn with_stage(mut self, stage: ProgressStage) -> Self {
200 self.stage = Some(stage);
201 self
202 }
203
204 /// Returns the event phase.
205 ///
206 /// # Returns
207 ///
208 /// The lifecycle phase carried by this event.
209 #[inline]
210 pub const fn phase(&self) -> ProgressPhase {
211 self.phase
212 }
213
214 /// Returns the current stage when known.
215 ///
216 /// # Returns
217 ///
218 /// `Some(stage)` when this event carries stage information, otherwise
219 /// `None`.
220 #[inline]
221 pub const fn stage(&self) -> Option<&ProgressStage> {
222 self.stage.as_ref()
223 }
224
225 /// Returns the progress counters.
226 ///
227 /// # Returns
228 ///
229 /// The counters carried by this event.
230 #[inline]
231 pub const fn counters(&self) -> ProgressCounters {
232 self.counters
233 }
234
235 /// Returns the elapsed duration.
236 ///
237 /// # Returns
238 ///
239 /// The monotonic elapsed duration carried by this event.
240 #[inline]
241 pub const fn elapsed(&self) -> Duration {
242 self.elapsed
243 }
244}