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
//! The handle that stops a run from another thread.
use ;
use crateNotice;
/// A handle that stops the runs that watch it.
///
/// A run watches a cancel that
/// [`RunOptions::cancel`](crate::RunOptions::cancel) gave it.
/// [`Cancel::cancel`] stops each watching run with its escalation, and the
/// run ends as [`Stopped(Cancelled)`](crate::StopReason::Cancelled). A run that
/// starts with a cancel that is already cancelled starts no child. Clones
/// share one state, so any clone cancels, and a cancel stays cancelled.
///
/// Any thread may call [`Cancel::cancel`] at any time, before, during or
/// after a run. A cancel that arrives once the run has seen the child's exit
/// changes nothing, and the run gives the child's own end. When the run sees
/// a cancel and the exit together, the exit wins. Otherwise the run gives
/// `Stopped(Cancelled)`, which a cancel just after the exit can also give.
/// [`ChildFinished::status`](crate::ChildFinished::status) gives the child's
/// own status in each case.
///
/// The run does not poll a flag of the caller's. A tool whose stop request is a flag, such
/// as one that a signal handler sets, polls that flag on a thread of its
/// own and calls [`Cancel::cancel`] from there. A signal handler itself must
/// not call it, because it takes a lock. Such a tool decides what the stop
/// means from its own flag, because a status such as `Signal(2)` also
/// follows a signal that another process sent.
///
/// ```
/// use std::process::Command;
/// use std::sync::Arc;
/// use std::sync::atomic::{AtomicBool, Ordering};
/// use std::time::Duration;
///
/// use crumbkit_process::{Cancel, RunOptions, run};
///
/// fn run_until(flag: &Arc<AtomicBool>, command: Command) -> bool {
/// let cancel = Cancel::new();
/// let done = Arc::new(AtomicBool::new(false));
/// let poller = std::thread::spawn({
/// let (flag, cancel, done) = (Arc::clone(flag), cancel.clone(), Arc::clone(&done));
/// move || {
/// while !done.load(Ordering::Relaxed) {
/// if flag.load(Ordering::Relaxed) {
/// cancel.cancel();
/// return;
/// }
/// std::thread::sleep(Duration::from_millis(10));
/// }
/// }
/// });
/// let finished = run(command, &RunOptions::new().cancel(&cancel));
/// done.store(true, Ordering::Relaxed);
/// let _ = poller.join();
/// finished.is_ok()
/// }
/// ```
;
/// Whether a cancel was cancelled, and the runs that watch it.