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///     ProgressCounter,
31///     ProgressSchema,
32/// };
33///
34/// let reporter = NoOpProgressReporter;
35///
36/// thread::scope(|scope| {
37///     let progress = Progress::new(
38///         &reporter,
39///         Duration::ZERO,
40///         ProgressSchema::single("entries", "Entries"),
41///     );
42///     let running_progress = progress.spawn_running_reporter(scope, || {
43///         vec![ProgressCounter::new("entries").total(1).completed(1)]
44///     });
45///     let progress_point_handle = running_progress.point_handle();
46///
47///     let worker = scope.spawn({
48///         let progress_point_handle = progress_point_handle.clone();
49///         move || {
50///             assert!(progress_point_handle.report());
51///         }
52///     });
53///     worker.join().unwrap();
54///
55///     running_progress.stop_and_join();
56/// });
57/// ```
58///
59/// # Author
60///
61/// Haixing Hu
62#[derive(Clone)]
63pub struct RunningProgressPointHandle {
64    /// Optional notifier used only when worker points should wake the loop.
65    notifier: Option<RunningProgressNotifier>,
66}
67
68impl RunningProgressPointHandle {
69    /// Creates a worker-side running point handle.
70    ///
71    /// # Parameters
72    ///
73    /// * `notifier` - Optional notifier used for zero-interval point signals.
74    ///
75    /// # Returns
76    ///
77    /// A worker-side handle that reports points or no-ops by interval policy.
78    #[inline]
79    pub(crate) const fn new(notifier: Option<RunningProgressNotifier>) -> Self {
80        Self { notifier }
81    }
82
83    /// Reports one worker running progress point.
84    ///
85    /// # Returns
86    ///
87    /// `true` when the point was accepted or no point signal is required.
88    /// Returns `false` only when a required zero-interval signal could not be
89    /// sent because the reporter loop has already stopped.
90    #[inline]
91    pub fn report(&self) -> bool {
92        match self.notifier.as_ref() {
93            Some(notifier) => notifier.running_point(),
94            None => true,
95        }
96    }
97}
qubit_progress/running/running_progress_point_handle.rs

qubit_progress/running/
running_progress_point_handle.rs
