qubit_progress/running/
running_progress_guard.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::{
11    panic::resume_unwind,
12    thread::ScopedJoinHandle,
13};
14
15use super::{
16    running_progress_notifier::RunningProgressNotifier,
17    running_progress_point_handle::RunningProgressPointHandle,
18};
19
20/// Owns a scoped running progress reporter thread.
21///
22/// `RunningProgressGuard` is created by
23/// [`Progress::spawn_running_reporter`](crate::Progress::spawn_running_reporter).
24/// Keep this guard on the coordinating thread, pass
25/// [`RunningProgressPointHandle`] clones to workers, and call
26/// [`Self::stop_and_join`] after worker execution completes.
27///
28/// # Examples
29///
30/// ```
31/// use std::{
32///     sync::{
33///         Arc,
34///         atomic::{
35///             AtomicUsize,
36///             Ordering,
37///         },
38///     },
39///     thread,
40///     time::Duration,
41/// };
42///
43/// use qubit_progress::{
44///     NoOpProgressReporter,
45///     Progress,
46///     ProgressCounters,
47/// };
48///
49/// let reporter = NoOpProgressReporter;
50/// let completed = Arc::new(AtomicUsize::new(0));
51///
52/// thread::scope(|scope| {
53///     let loop_completed = Arc::clone(&completed);
54///     let progress = Progress::new(&reporter, Duration::ZERO);
55///     let running_progress =
56///         progress.spawn_running_reporter(scope, move || {
57///             ProgressCounters::new(Some(3))
58///                 .with_completed_count(loop_completed.load(Ordering::Acquire))
59///         });
60///     let progress_point_handle = running_progress.point_handle();
61///
62///     let mut handles = Vec::new();
63///     for _ in 0..3 {
64///         let c = Arc::clone(&completed);
65///         let p = progress_point_handle.clone();
66///         handles.push(scope.spawn(move || {
67///             c.fetch_add(1, Ordering::AcqRel);
68///             assert!(p.report());
69///         }));
70///     }
71///     for h in handles {
72///         h.join().unwrap();
73///     }
74///
75///     running_progress.stop_and_join();
76/// });
77/// ```
78///
79/// # Author
80///
81/// Haixing Hu
82pub struct RunningProgressGuard<'scope> {
83    /// Notifier used to stop the reporter thread.
84    notifier: RunningProgressNotifier,
85    /// Scoped reporter thread handle.
86    progress_thread: ScopedJoinHandle<'scope, ()>,
87    /// Whether worker point notifications should wake the reporter loop.
88    report_points: bool,
89}
90
91impl<'scope> RunningProgressGuard<'scope> {
92    /// Creates a scoped running progress guard.
93    ///
94    /// # Parameters
95    ///
96    /// * `notifier` - Notifier used to stop the reporter thread.
97    /// * `progress_thread` - Scoped reporter thread handle.
98    /// * `report_points` - Whether worker point notifications wake the loop.
99    ///
100    /// # Returns
101    ///
102    /// A guard owning the reporter thread lifecycle.
103    #[inline]
104    pub(crate) const fn new(
105        notifier: RunningProgressNotifier,
106        progress_thread: ScopedJoinHandle<'scope, ()>,
107        report_points: bool,
108    ) -> Self {
109        Self {
110            notifier,
111            progress_thread,
112            report_points,
113        }
114    }
115
116    /// Returns a worker-side running point handle.
117    ///
118    /// # Returns
119    ///
120    /// A cloneable handle that wakes the reporter loop for zero intervals and
121    /// becomes a no-op for positive intervals.
122    #[inline]
123    pub fn point_handle(&self) -> RunningProgressPointHandle {
124        RunningProgressPointHandle::new(self.report_points.then(|| self.notifier.clone()))
125    }
126
127    /// Stops the reporter loop and joins the scoped reporter thread.
128    ///
129    /// # Panics
130    ///
131    /// Propagates any panic raised by the reporter thread.
132    #[inline]
133    pub fn stop_and_join(self) {
134        self.notifier.stop();
135        if let Err(payload) = self.progress_thread.join() {
136            resume_unwind(payload);
137        }
138    }
139}
qubit_progress/running/running_progress_guard.rs

qubit_progress/running/
running_progress_guard.rs
