Skip to main content

StreamVisitor

tokio_process_tools

Trait StreamVisitor 

Source 
pub trait StreamVisitor: Send + 'static {
    type Output: Send + 'static;

    // Required methods
    fn on_chunk(&mut self, chunk: Chunk) -> Next;
    fn into_output(self) -> Self::Output;

    // Provided methods
    fn on_gap(&mut self) { ... }
    fn on_eof(&mut self) { ... }
}
Expand description

A synchronous visitor that observes stream events and produces a final value.

StreamVisitor is the synchronous counterpart to AsyncStreamVisitor. Implement it on a type that needs to react to chunks, gaps, and EOF without .await-ing between events, then drive it via consume_with to obtain a Consumer handle that owns the resulting tokio task.

All built-in consumer factories (inspect_*, collect_*, wait_for_line) construct a built-in visitor and call consume_with internally; this trait is what users implement to plug in custom logic without wrapping a closure in shared mutable state.

§Lifecycle

  1. on_chunk is invoked for every observed chunk. Return Next::Continue to keep going or Next::Break to stop early.
  2. on_gap is invoked when the stream backend reports that chunks were dropped (e.g., best-effort delivery overflow). Use it to reset partial-line buffers or other accumulated state.
  3. on_eof is invoked exactly once when the stream ends naturally. It is not invoked when the visitor returned Next::Break, nor when the consumer task is cancelled or aborted.
  4. into_output consumes self and returns the value the Consumer’s wait/cancel methods yield.

§Example

/// Counts chunks and stops after `limit`.
struct CountUntil { count: usize, limit: usize }

impl StreamVisitor for CountUntil {
    type Output = usize;

    fn on_chunk(&mut self, _chunk: Chunk) -> Next {
        self.count += 1;
        if self.count >= self.limit { Next::Break } else { Next::Continue }
    }

    fn into_output(self) -> usize { self.count }
}

Required Associated Types§

Source

type Output: Send + 'static

The value produced by into_output after the visitor has finished observing the stream. Returned via Consumer::wait and Consumer::cancel.

Required Methods§

Source

fn on_chunk(&mut self, chunk: Chunk) -> Next

Invoked for every chunk observed on the stream.

Return Next::Continue to keep visiting, or Next::Break to stop without consuming further events; in the latter case on_eof is not called.

Source

fn into_output(self) -> Self::Output

Consumes the visitor and returns its final output.

Called after the visitor has stopped observing events (via EOF, Break, or cancellation). The returned value is what the owning Consumer’s wait/cancel methods yield.

Provided Methods§

Source

fn on_gap(&mut self)

Invoked when the stream backend reports that one or more chunks were dropped between the last delivered chunk and the next one.

The default implementation does nothing. Override it to reset any partial-line buffers or other accumulated state that would be invalidated by the gap.

Whether gaps can occur depends on the guarantees chosen for the backend.

Source

fn on_eof(&mut self)

Invoked exactly once when the stream ends (EOF or write side dropped).

Not called when the visitor returned Next::Break from on_chunk, nor when the consumer task is cancelled or aborted before the stream ends.

Implementors§