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

qubit_progress/running/
running_progress_point_handle.rs
