Skip to main content

crumbkit_process/run/
output.rs

1//! What a run keeps of each output stream.
2
3use std::fmt;
4use std::process::Stdio;
5use std::sync::Arc;
6use std::time::Instant;
7
8use crate::LineQueue;
9
10#[cfg(test)]
11mod tests;
12
13/// The bytes that a tail keeps beyond its limit before it drops the oldest,
14/// so a long stream is not moved on every read.
15const SLACK: usize = 8 * 1024;
16
17/// What a run keeps of one output stream of the child.
18///
19/// A constructor chooses the kind of capture. [`Capture::whole`] and
20/// [`Capture::lines`] return a builder for the settings of their kind, which
21/// [`RunOptions::stdout`](crate::RunOptions::stdout) and
22/// [`RunOptions::stderr`](crate::RunOptions::stderr) take as it is. The
23/// default is [`Capture::discard`].
24#[derive(Clone, Debug, Default)]
25pub struct Capture(Kind);
26
27/// The kind of a capture and the settings of that kind.
28#[derive(Clone, Debug, Default)]
29enum Kind {
30    #[default]
31    Discard,
32    Inherit,
33    Whole(WholeCapture),
34    Tail {
35        limit: usize,
36    },
37    Lines(LineCapture),
38}
39
40/// A capture that keeps the first bytes of a stream, from
41/// [`Capture::whole`].
42#[derive(Clone, Debug)]
43#[must_use]
44pub struct WholeCapture {
45    limit: usize,
46    over: OverLimit,
47}
48
49/// A capture that delivers a stream as lines, from [`Capture::lines`].
50#[derive(Clone, Debug)]
51#[must_use]
52pub struct LineCapture {
53    queue: LineQueue,
54    line: usize,
55    total: usize,
56    over: OverLimit,
57    long: LongLine,
58    end: u8,
59}
60
61/// What a line longer than the limit of one line does to a stream
62/// delivered as lines.
63#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
64#[non_exhaustive]
65pub enum LongLine {
66    /// The stream is over its limit, and its `over` policy applies.
67    #[default]
68    Over,
69    /// The run drops that line up to its end and delivers the next line.
70    /// [`Captured::long_line`] tells that it dropped at least one line, and
71    /// [`Captured::over_limit`] stays false unless the total limit passes.
72    Skip,
73}
74
75/// What a run does when a stream that it keeps whole or as lines passes
76/// its limit.
77#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
78#[non_exhaustive]
79pub enum OverLimit {
80    /// The run stops the child with its escalation and ends as
81    /// [`Stopped(OverLimit)`](crate::StopReason::OverLimit).
82    #[default]
83    Stop,
84    /// The run reads the rest of the stream and drops it, so the child
85    /// never waits on a full pipe and runs to its end.
86    Sink,
87}
88
89impl Capture {
90    /// Returns a capture that sends the stream to the null device and keeps
91    /// nothing.
92    #[must_use]
93    pub const fn discard() -> Self {
94        Self(Kind::Discard)
95    }
96
97    /// Returns a capture that sends the stream to the tool's own stream and
98    /// keeps nothing.
99    ///
100    /// A child in a group of its own is in the background of the terminal.
101    /// It can write there unless the terminal has `tostop` set, and it is
102    /// stopped when it reads. A stopped child holds a run with no deadline.
103    /// For a step that the person answers, use
104    /// [`Scope::Child`](crate::Scope::Child) with
105    /// [`Input::Inherit`](crate::Input::Inherit), so the child stays in the
106    /// tool's foreground group and the tool carries on when it ends. Ctrl-C
107    /// then reaches both.
108    #[must_use]
109    pub const fn inherit() -> Self {
110        Self(Kind::Inherit)
111    }
112
113    /// Returns a capture that reads the whole stream and keeps its last
114    /// `limit` bytes.
115    #[must_use]
116    pub const fn tail(limit: usize) -> Self {
117        Self(Kind::Tail { limit })
118    }
119
120    /// Returns a capture that keeps the stream's first `limit` bytes.
121    ///
122    /// A stream longer than `limit` bytes is over its limit, and the run
123    /// stops the child then unless [`WholeCapture::over`] says otherwise.
124    pub const fn whole(limit: usize) -> WholeCapture {
125        WholeCapture {
126            limit,
127            over: OverLimit::Stop,
128        }
129    }
130
131    /// Returns a capture that splits the stream into lines and pushes each
132    /// line, without its end, to `queue` while the child runs. A last line
133    /// with no end is pushed when the stream ends. The run keeps no bytes in
134    /// its [`Captured`].
135    ///
136    /// The first time the stream passes `total` bytes, line ends and
137    /// skipped lines included, the stream is over its limit. No line is
138    /// pushed after that, and the run stops the child unless
139    /// [`LineCapture::over`] says otherwise. Without
140    /// [`LineCapture::line`], one line has no limit of its own, and lines
141    /// end at `b'\n'` unless [`LineCapture::end`] names another byte.
142    ///
143    /// `queue` comes from [`line_queue`](crate::line_queue) and serves one
144    /// run, which ends it when it returns.
145    pub const fn lines(queue: LineQueue, total: usize) -> LineCapture {
146        LineCapture {
147            queue,
148            line: usize::MAX,
149            total,
150            over: OverLimit::Stop,
151            long: LongLine::Over,
152            end: b'\n',
153        }
154    }
155
156    /// Returns the standard stream that the child gets for this capture.
157    pub(super) fn stdio(&self) -> Stdio {
158        match self.0 {
159            Kind::Discard => Stdio::null(),
160            Kind::Inherit => Stdio::inherit(),
161            Kind::Whole(_) | Kind::Tail { .. } | Kind::Lines(_) => Stdio::piped(),
162        }
163    }
164
165    /// Returns true when the capture sends the stream to the tool's own.
166    pub(super) const fn inherits(&self) -> bool {
167        matches!(self.0, Kind::Inherit)
168    }
169
170    /// Returns the queue of a stream delivered as lines.
171    const fn queue(&self) -> Option<&LineQueue> {
172        match &self.0 {
173            Kind::Lines(lines) => Some(&lines.queue),
174            _ => None,
175        }
176    }
177
178    /// Tells the queue of a stream delivered as lines that the run began
179    /// to stop its child, so a full queue drops a line instead of waiting.
180    pub(super) fn stopping(&self) {
181        if let Some(queue) = self.queue() {
182            queue.stopping();
183        }
184    }
185
186    /// Tells the queue of a stream delivered as lines that the child has
187    /// been reaped, so a full queue drops a line once `deadline` has
188    /// passed.
189    pub(super) fn drain_until(&self, deadline: Instant) {
190        if let Some(queue) = self.queue() {
191            queue.drain_until(deadline);
192        }
193    }
194
195    /// Ends the queue of a stream delivered as lines, so the caller's
196    /// waits end once the queue is empty.
197    pub(super) fn end(&self) {
198        if let Some(queue) = self.queue() {
199            queue.end();
200        }
201    }
202}
203
204impl WholeCapture {
205    /// Sets what the run does when the stream passes its limit. Without
206    /// it, the run stops the child.
207    pub const fn over(mut self, over: OverLimit) -> Self {
208        self.over = over;
209        self
210    }
211}
212
213impl From<WholeCapture> for Capture {
214    fn from(whole: WholeCapture) -> Self {
215        Self(Kind::Whole(whole))
216    }
217}
218
219impl LineCapture {
220    /// Sets the most bytes of one line, without its end. Without it, one
221    /// line has no limit of its own, and only the total limit applies.
222    pub const fn line(mut self, line: usize) -> Self {
223        self.line = line;
224        self
225    }
226
227    /// Sets what a line longer than the limit of one line does. Without it,
228    /// such a line takes the stream over its limit, as [`LongLine::Over`]
229    /// says.
230    pub const fn long(mut self, long: LongLine) -> Self {
231        self.long = long;
232        self
233    }
234
235    /// Sets what the run does when the stream passes a limit. Without it,
236    /// the run stops the child.
237    pub const fn over(mut self, over: OverLimit) -> Self {
238        self.over = over;
239        self
240    }
241
242    /// Sets the byte that ends a line, such as `0`. Without it, a line ends
243    /// at `b'\n'`.
244    pub const fn end(mut self, end: u8) -> Self {
245        self.end = end;
246        self
247    }
248}
249
250impl From<LineCapture> for Capture {
251    fn from(lines: LineCapture) -> Self {
252        Self(Kind::Lines(lines))
253    }
254}
255
256/// What a run kept of one output stream.
257#[derive(Clone, Debug, Default, PartialEq, Eq)]
258pub struct Captured {
259    bytes: Vec<u8>,
260    over_limit: bool,
261    long_line: bool,
262}
263
264impl Captured {
265    /// Returns the kept bytes: the first bytes of a stream kept whole, the
266    /// last bytes of a tail, and nothing of a discarded stream.
267    #[must_use]
268    pub fn bytes(&self) -> &[u8] {
269        &self.bytes
270    }
271
272    /// Returns the kept bytes, consuming what was captured.
273    #[must_use]
274    pub fn into_bytes(self) -> Vec<u8> {
275        self.bytes
276    }
277
278    /// Returns true when the stream was longer than its limit, so the kept
279    /// bytes, or the lines delivered, are not all of it.
280    #[must_use]
281    pub const fn over_limit(&self) -> bool {
282        self.over_limit
283    }
284
285    /// Returns true when the run acted on a line of a stream delivered as
286    /// lines that passed the limit of one line: that line took the stream
287    /// over its limit with [`LongLine::Over`], or the run dropped it with
288    /// [`LongLine::Skip`]. A line does not count when the bytes that first
289    /// take it over its own limit also take the stream over the total limit,
290    /// and only [`Captured::over_limit`] tells.
291    #[must_use]
292    pub const fn long_line(&self) -> bool {
293        self.long_line
294    }
295}
296
297/// The caller's function that receives each chunk of one output stream.
298#[derive(Clone)]
299pub(super) struct OutputCopy(Arc<CopyFn>);
300
301/// The caller's function, which the settings hold and a reader thread calls.
302type CopyFn = dyn Fn(&[u8]) + Send + Sync;
303
304impl OutputCopy {
305    /// Wraps the caller's function.
306    pub(super) fn new(copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self {
307        Self(Arc::new(copy))
308    }
309
310    /// Gives `chunk` to the caller's function.
311    pub(super) fn send(&self, chunk: &[u8]) {
312        (self.0)(chunk);
313    }
314}
315
316impl fmt::Debug for OutputCopy {
317    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
318        f.write_str("OutputCopy(..)")
319    }
320}
321
322/// Keeps the bytes of one stream as its [`Capture`] says.
323#[derive(Debug)]
324pub(super) struct Keeper {
325    capture: Capture,
326    kept: Captured,
327    /// The bytes of the line that a stream delivered as lines has not yet
328    /// ended.
329    line: Vec<u8>,
330    /// The bytes that a stream delivered as lines has read in all.
331    read: usize,
332    /// False once the caller has dropped its side of the line queue.
333    listening: bool,
334    /// True while a stream delivered as lines drops the rest of a long line.
335    skipping: bool,
336}
337
338impl Keeper {
339    /// Returns a keeper that keeps what `capture` asks for.
340    pub(super) fn new(capture: &Capture) -> Self {
341        Self {
342            capture: capture.clone(),
343            kept: Captured::default(),
344            line: Vec::new(),
345            read: 0,
346            listening: true,
347            skipping: false,
348        }
349    }
350
351    /// Keeps what it should of `bytes`, which the stream yielded next, and
352    /// returns true when these bytes take a stream whose policy stops the
353    /// child over its limit for the first time.
354    pub(super) fn add(&mut self, bytes: &[u8]) -> bool {
355        let kept = &mut self.kept;
356        match self.capture.0 {
357            Kind::Discard | Kind::Inherit => false,
358            Kind::Lines(LineCapture {
359                line,
360                total,
361                over,
362                long,
363                end,
364                ..
365            }) => self.add_lines(bytes, line, total, long, end) && over == OverLimit::Stop,
366            Kind::Whole(WholeCapture { limit, over }) => {
367                let room = limit.saturating_sub(kept.bytes.len());
368                kept.bytes
369                    .extend_from_slice(&bytes[..room.min(bytes.len())]);
370                if bytes.len() <= room || kept.over_limit {
371                    return false;
372                }
373                kept.over_limit = true;
374                over == OverLimit::Stop
375            }
376            Kind::Tail { limit } => {
377                kept.bytes.extend_from_slice(bytes);
378                if kept.bytes.len() > limit.saturating_add(SLACK) {
379                    kept.bytes.drain(..kept.bytes.len() - limit);
380                    kept.over_limit = true;
381                }
382                false
383            }
384        }
385    }
386
387    /// Splits `bytes` into lines and pushes each complete line, and
388    /// returns true when these bytes take the stream over `line` bytes for
389    /// one line or `total` bytes in all for the first time.
390    fn add_lines(
391        &mut self,
392        bytes: &[u8],
393        line: usize,
394        total: usize,
395        long: LongLine,
396        end: u8,
397    ) -> bool {
398        if self.kept.over_limit {
399            return false;
400        }
401        let mut rest = bytes;
402        loop {
403            let (piece, ended) = match rest.iter().position(|byte| *byte == end) {
404                Some(at) => (&rest[..at], true),
405                None => (rest, false),
406            };
407            self.read = self.read.saturating_add(piece.len() + usize::from(ended));
408            if !self.skipping {
409                self.line.extend_from_slice(piece);
410            }
411            let over_line = self.line.len() > line;
412            if self.read > total || (over_line && long == LongLine::Over) {
413                self.kept.over_limit = true;
414                self.kept.long_line |= over_line && self.read <= total;
415                self.line = Vec::new();
416                return true;
417            }
418            if over_line {
419                self.skipping = true;
420                self.kept.long_line = true;
421                self.line = Vec::new();
422            }
423            if !ended {
424                return false;
425            }
426            if self.skipping {
427                self.skipping = false;
428            } else {
429                self.push_line();
430            }
431            rest = &rest[piece.len() + 1..];
432            if rest.is_empty() {
433                return false;
434            }
435        }
436    }
437
438    /// Pushes the line kept so far to the queue of a stream delivered as
439    /// lines, unless the caller has dropped its side.
440    fn push_line(&mut self) {
441        let line = std::mem::take(&mut self.line);
442        if let Some(queue) = self.capture.queue()
443            && self.listening
444        {
445            self.listening = queue.push(line);
446        }
447    }
448
449    /// Returns what was kept once the stream has ended. A stream delivered
450    /// as lines pushes its last line when that line has no end byte.
451    pub(super) fn finish(mut self) -> Captured {
452        if self.capture.queue().is_some() && !self.kept.over_limit && !self.line.is_empty() {
453            self.push_line();
454        }
455        if let Kind::Tail { limit } = self.capture.0
456            && self.kept.bytes.len() > limit
457        {
458            self.kept.bytes.drain(..self.kept.bytes.len() - limit);
459            self.kept.over_limit = true;
460        }
461        self.kept
462    }
463}