Skip to main content

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