crumbkit_process/lines.rs
1//! The bounded queue that carries the lines of one output stream from the
2//! run's reader to the caller while the run goes on.
3//!
4//! A full queue makes the reader wait, and the child then waits on its full
5//! pipe. Once the run begins to stop the child, a line that finds the queue
6//! full is dropped and kept as `lost` until a later line is queued, so a
7//! caller that stopped reading cannot hold up the stop. After the child
8//! exits by itself, a full queue keeps waiting for the caller until half of
9//! the run's drain grace has passed since the reap, and then drops lines in
10//! the same way. Once the caller drops its [`Lines`], the reader reads the
11//! rest of the stream and drops it.
12
13use std::collections::VecDeque;
14use std::fmt;
15use std::sync::{Arc, Condvar, Mutex, MutexGuard, PoisonError};
16use std::time::{Duration, Instant};
17
18#[cfg(test)]
19mod tests;
20
21/// Returns a queue that holds at most `most` lines, or one line when
22/// `most` is 0: the side that a run fills, which
23/// [`Capture::Lines`](crate::Capture::Lines) takes, and the caller's side.
24///
25/// Each queue serves one run. The run ends the queue when it returns, on
26/// every path, including a start failure and a cancel before the start, so
27/// [`Lines::recv`] then returns `None` once the queue is empty.
28#[must_use]
29pub fn line_queue(most: usize) -> (LineQueue, Lines) {
30 let shared = Arc::new(Shared {
31 most: most.max(1),
32 state: Mutex::new(State::default()),
33 changed: Condvar::new(),
34 });
35 (LineQueue(Arc::clone(&shared)), Lines(shared))
36}
37
38/// What the run's reader and the caller share.
39#[derive(Debug)]
40struct Shared {
41 most: usize,
42 state: Mutex<State>,
43 changed: Condvar,
44}
45
46/// The queued lines and what has happened to the run and the caller.
47#[derive(Debug, Default)]
48struct State {
49 lines: VecDeque<Vec<u8>>,
50 /// The last line that a full queue dropped, while no line has been
51 /// queued after it, because queuing a line clears it. It is the
52 /// stream's last line only when the reader reached the end of the pipe
53 /// and the stream stayed within its limit.
54 lost: Option<Vec<u8>>,
55 stopping: bool,
56 /// After the run has reaped the child, on every path including a stop,
57 /// the time after which a full queue drops lines.
58 drain_until: Option<Instant>,
59 ended: bool,
60 abandoned: bool,
61}
62
63/// The side of a line queue that a run fills. A run takes it in
64/// [`Capture::Lines`](crate::Capture::Lines).
65#[derive(Clone)]
66pub struct LineQueue(Arc<Shared>);
67
68impl fmt::Debug for LineQueue {
69 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70 f.debug_struct("LineQueue")
71 .field("most", &self.0.most)
72 .finish_non_exhaustive()
73 }
74}
75
76impl LineQueue {
77 /// Adds `line`, and waits while the queue is full, the run is not
78 /// stopping, the drain deadline has not passed and the caller still
79 /// holds its [`Lines`]. A full queue after the run began to stop, or
80 /// after the drain deadline, drops the line and keeps it as `lost`
81 /// until a later line is queued. Returns false when the caller has
82 /// dropped its side, and then nobody reads the line.
83 pub(crate) fn push(&self, line: Vec<u8>) -> bool {
84 let shared = &*self.0;
85 let mut state = shared.lock();
86 while state.lines.len() >= shared.most && !state.stopping && !state.abandoned {
87 state = if let Some(deadline) = state.drain_until {
88 let Some(left) = deadline.checked_duration_since(Instant::now()) else {
89 break;
90 };
91 shared
92 .changed
93 .wait_timeout(state, left)
94 .unwrap_or_else(PoisonError::into_inner)
95 .0
96 } else {
97 shared
98 .changed
99 .wait(state)
100 .unwrap_or_else(PoisonError::into_inner)
101 };
102 }
103 if state.abandoned {
104 return false;
105 }
106 if state.lines.len() < shared.most {
107 state.lines.push_back(line);
108 state.lost = None;
109 shared.changed.notify_all();
110 } else {
111 state.lost = Some(line);
112 }
113 true
114 }
115
116 /// Marks that the run began to stop its child, so a full queue drops
117 /// a line instead of waiting.
118 pub(crate) fn stopping(&self) {
119 self.0.lock().stopping = true;
120 self.0.changed.notify_all();
121 }
122
123 /// Marks that the run has reaped the child, on every path including a
124 /// stop, so a full queue waits for the caller only until `deadline` and
125 /// then drops a line instead.
126 pub(crate) fn drain_until(&self, deadline: Instant) {
127 self.0.lock().drain_until = Some(deadline);
128 self.0.changed.notify_all();
129 }
130
131 /// Marks that the run has ended, so the caller's waits end once the
132 /// queue is empty.
133 pub(crate) fn end(&self) {
134 self.0.lock().ended = true;
135 self.0.changed.notify_all();
136 }
137}
138
139/// The caller's side of a line queue, which yields each line of the stream
140/// without its end byte as the run reads it. Dropping it tells the run that
141/// nobody reads the lines, and the run reads the rest of the stream and
142/// drops it.
143pub struct Lines(Arc<Shared>);
144
145impl fmt::Debug for Lines {
146 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
147 f.debug_struct("Lines")
148 .field("most", &self.0.most)
149 .finish_non_exhaustive()
150 }
151}
152
153/// No line arrived and the run did not end within the time that
154/// [`Lines::recv_timeout`] waited.
155#[derive(Clone, Copy, Debug, PartialEq, Eq)]
156pub struct Silent;
157
158impl fmt::Display for Silent {
159 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
160 f.write_str("no line arrived in time")
161 }
162}
163
164impl std::error::Error for Silent {}
165
166impl Lines {
167 /// Waits for the next line and returns it, or returns `None` once the
168 /// run has ended and every queued line has been returned.
169 #[must_use]
170 pub fn recv(&self) -> Option<Vec<u8>> {
171 let shared = &*self.0;
172 let mut state = shared.lock();
173 while state.lines.is_empty() && !state.ended {
174 state = shared
175 .changed
176 .wait(state)
177 .unwrap_or_else(PoisonError::into_inner);
178 }
179 shared.take(&mut state)
180 }
181
182 /// Waits at most `timeout` for the next line, as [`Lines::recv`] does.
183 ///
184 /// # Errors
185 ///
186 /// Returns [`Silent`] when no line arrived and the run did not end
187 /// within `timeout`.
188 pub fn recv_timeout(&self, timeout: Duration) -> Result<Option<Vec<u8>>, Silent> {
189 let shared = &*self.0;
190 // A timeout too long for an `Instant` waits without a limit.
191 let deadline = Instant::now().checked_add(timeout);
192 let mut state = shared.lock();
193 while state.lines.is_empty() && !state.ended {
194 let left = deadline.map_or(timeout, |deadline| {
195 deadline.saturating_duration_since(Instant::now())
196 });
197 if left.is_zero() {
198 return Err(Silent);
199 }
200 state = shared
201 .changed
202 .wait_timeout(state, left)
203 .unwrap_or_else(PoisonError::into_inner)
204 .0;
205 }
206 Ok(shared.take(&mut state))
207 }
208
209 /// Returns the last line that a full queue dropped, after the run began
210 /// to stop or half of the run's drain grace passed since the reap, so
211 /// [`Lines::recv`] never returned it. It is the stream's last line when
212 /// the reader reached the end of the pipe, which it does in the other
213 /// half of the grace. Three cases leave it as another line. A process
214 /// outside the child's group that holds the pipe open and goes on
215 /// writing, or a reader too slow to reach the end, leaves it as the last
216 /// line read when the reads ended, which can be part of a line. A stream
217 /// over its limit stops pushing lines while the reader goes on, so it is
218 /// the last line dropped before the limit, and
219 /// [`Captured::over_limit`](crate::Captured::over_limit) shows that
220 /// case. A line queued after the last drop clears it, so `None` does not
221 /// show that no line was dropped. It returns `None` until the run has
222 /// ended, and the line only once.
223 #[must_use]
224 pub fn lost(&self) -> Option<Vec<u8>> {
225 let mut state = self.0.lock();
226 if state.ended { state.lost.take() } else { None }
227 }
228}
229
230impl Drop for Lines {
231 /// Tells the run that nobody reads the lines, so its reader stops
232 /// waiting for room.
233 fn drop(&mut self) {
234 self.0.lock().abandoned = true;
235 self.0.changed.notify_all();
236 }
237}
238
239impl Shared {
240 /// Takes the next line from `state`, and wakes a reader that waits for
241 /// room.
242 fn take(&self, state: &mut State) -> Option<Vec<u8>> {
243 let line = state.lines.pop_front();
244 if line.is_some() {
245 self.changed.notify_all();
246 }
247 line
248 }
249
250 /// Returns the locked state. Each holder changes it in one step, so a
251 /// panic while the lock was held leaves nothing half changed.
252 fn lock(&self) -> MutexGuard<'_, State> {
253 self.state.lock().unwrap_or_else(PoisonError::into_inner)
254 }
255}