qubit_progress/running/
running_progress_point_handle.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 super::running_progress_notifier::RunningProgressNotifier;
11
12/// Worker-side handle for reporting running progress points.
13///
14/// `RunningProgressPointHandle` deliberately cannot stop or join the reporter
15/// thread. It only wakes the reporter loop for zero-interval progress. For
16/// positive intervals, [`Self::report`] is a no-op because the reporter
17/// loop wakes itself on timeout.
18///
19/// # Examples
20///
21/// ```
22/// use std::{
23///     thread,
24///     time::Duration,
25/// };
26///
27/// use qubit_progress::{
28///     NoOpProgressReporter,
29///     Progress,
30///     ProgressCounters,
31///     RunningProgressLoop,
32/// };
33///
34/// let reporter = NoOpProgressReporter;
35///
36/// thread::scope(|scope| {
37///     let progress = Progress::new(&reporter, Duration::ZERO);
38///     let running_progress =
39///         RunningProgressLoop::spawn_scoped(scope, progress, || {
40///             ProgressCounters::new(Some(1)).with_completed_count(1)
41///         });
42///     let progress_point_handle = running_progress.point_handle();
43///
44///     assert!(progress_point_handle.report());
45///
46///     running_progress.stop_and_join();
47/// });
48/// ```
49///
50/// # Author
51///
52/// Haixing Hu
53#[derive(Clone)]
54pub struct RunningProgressPointHandle {
55    /// Optional notifier used only when worker points should wake the loop.
56    notifier: Option<RunningProgressNotifier>,
57}
58
59impl RunningProgressPointHandle {
60    /// Creates a worker-side running point handle.
61    ///
62    /// # Parameters
63    ///
64    /// * `notifier` - Optional notifier used for zero-interval point signals.
65    ///
66    /// # Returns
67    ///
68    /// A worker-side handle that reports points or no-ops by interval policy.
69    #[inline]
70    pub(crate) const fn new(notifier: Option<RunningProgressNotifier>) -> Self {
71        Self { notifier }
72    }
73
74    /// Reports one worker running progress point.
75    ///
76    /// # Returns
77    ///
78    /// `true` when the point was accepted or no point signal is required.
79    /// Returns `false` only when a required zero-interval signal could not be
80    /// sent because the reporter loop has already stopped.
81    #[inline]
82    pub fn report(&self) -> bool {
83        match self.notifier.as_ref() {
84            Some(notifier) => notifier.running_point(),
85            None => true,
86        }
87    }
88}
qubit_progress/running/running_progress_point_handle.rs

qubit_progress/running/
running_progress_point_handle.rs
