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    /// Returns a copy configured with the current stage.
164    ///
165    /// # Parameters
166    ///
167    /// * `stage` - Current operation stage.
168    ///
169    /// # Returns
170    ///
171    /// This event with `stage` recorded.
172    #[inline]
173    pub fn with_stage(mut self, stage: ProgressStage) -> Self {
174        self.stage = Some(stage);
175        self
176    }
177
178    /// Returns the event phase.
179    ///
180    /// # Returns
181    ///
182    /// The lifecycle phase carried by this event.
183    #[inline]
184    pub const fn phase(&self) -> ProgressPhase {
185        self.phase
186    }
187
188    /// Returns the current stage when known.
189    ///
190    /// # Returns
191    ///
192    /// `Some(stage)` when this event carries stage information, otherwise
193    /// `None`.
194    #[inline]
195    pub const fn stage(&self) -> Option<&ProgressStage> {
196        self.stage.as_ref()
197    }
198
199    /// Returns the progress counters.
200    ///
201    /// # Returns
202    ///
203    /// The counters carried by this event.
204    #[inline]
205    pub const fn counters(&self) -> ProgressCounters {
206        self.counters
207    }
208
209    /// Returns the elapsed duration.
210    ///
211    /// # Returns
212    ///
213    /// The monotonic elapsed duration carried by this event.
214    #[inline]
215    pub const fn elapsed(&self) -> Duration {
216        self.elapsed
217    }
218}
qubit_progress/model/progress_event.rs

qubit_progress/model/
progress_event.rs
