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

qubit_progress/running/
running_progress_point_handle.rs
