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}