1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
// Sylva: terrestrial laser scanning processing for forest ecology.
// Copyright (C) 2026 Tim Devereux, The University of Queensland.
// Free software under the GNU General Public License v3.0 or later;
// see the LICENSE file. There is no warranty, to the extent permitted by law.
//! Progress reporting for the long-running work.
//!
//! A function that takes a while opens a [`Task`] with a label and how many
//! steps it expects, then counts up as it goes. Counting is a single atomic
//! add, so a worker thread can do it inside a parallel loop; nothing is
//! printed and nothing is locked on that path. A caller that wants to show
//! progress reads [`state`] from another thread as often as it likes, which
//! is how the Python bindings drive a progress bar without ever touching the
//! threads doing the work.
//!
//! Tasks nest: a stage that runs inside another appears after it in `state`,
//! innermost last. Nothing is reported unless someone asks, and a task that
//! is dropped without finishing simply disappears.
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
/// One running stage: what it is, how far it has got, and how far it goes.
#[derive(Debug)]
pub struct Frame {
pub label: String,
pub done: AtomicU64,
pub total: AtomicU64,
}
fn stack() -> &'static Mutex<Vec<Arc<Frame>>> {
static STACK: OnceLock<Mutex<Vec<Arc<Frame>>>> = OnceLock::new();
STACK.get_or_init(|| Mutex::new(Vec::new()))
}
/// A stage in progress; it leaves the list when dropped.
#[derive(Debug)]
pub struct Task {
frame: Arc<Frame>,
}
/// Start a stage of `total` steps (0 if the count is not known yet).
pub fn start(label: impl Into<String>, total: u64) -> Task {
let frame = Arc::new(Frame { label: label.into(), done: AtomicU64::new(0), total: AtomicU64::new(total) });
if let Ok(mut s) = stack().lock() {
s.push(Arc::clone(&frame));
}
Task { frame }
}
impl Task {
/// Count `n` more steps done.
pub fn inc(&self, n: u64) {
self.frame.done.fetch_add(n, Ordering::Relaxed);
}
/// Set how many steps are done.
pub fn set(&self, done: u64) {
self.frame.done.store(done, Ordering::Relaxed);
}
/// Set how many steps there are, once that is known.
pub fn set_total(&self, total: u64) {
self.frame.total.store(total, Ordering::Relaxed);
}
}
impl Drop for Task {
fn drop(&mut self) {
if let Ok(mut s) = stack().lock() {
s.retain(|f| !Arc::ptr_eq(f, &self.frame));
}
}
}
/// The stages running now, outermost first, as `(label, done, total)`.
pub fn state() -> Vec<(String, u64, u64)> {
match stack().lock() {
Ok(s) => s
.iter()
.map(|f| (f.label.clone(), f.done.load(Ordering::Relaxed), f.total.load(Ordering::Relaxed)))
.collect(),
Err(_) => Vec::new(),
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Only this test's own frames: the registry is global, and the other
/// tests of the crate run at the same time.
fn mine(prefix: &str) -> Vec<(String, u64, u64)> {
state().into_iter().filter(|(l, _, _)| l.starts_with(prefix)).collect()
}
#[test]
fn tasks_nest_and_leave_when_dropped() {
let outer = start("test-nest outer", 10);
outer.inc(3);
{
let inner = start("test-nest inner", 4);
inner.inc(1);
inner.inc(1);
let s = mine("test-nest");
assert_eq!(s.len(), 2);
assert_eq!(s[0], ("test-nest outer".to_string(), 3, 10));
assert_eq!(s[1], ("test-nest inner".to_string(), 2, 4));
}
let s = mine("test-nest");
assert_eq!(s.len(), 1, "the inner task left when it was dropped");
outer.set(10);
outer.set_total(12);
assert_eq!(mine("test-nest")[0], ("test-nest outer".to_string(), 10, 12));
drop(outer);
assert!(mine("test-nest").is_empty());
}
#[test]
fn counting_works_from_several_threads() {
let t = start("test-threads", 400);
std::thread::scope(|s| {
for _ in 0..4 {
s.spawn(|| (0..100).for_each(|_| t.inc(1)));
}
});
assert_eq!(mine("test-threads")[0].1, 400);
}
}