Struct BoundedStream 

pub struct BoundedStream { /* private fields */ }

A bounded stream backed by a ring buffer.

When writes exceed capacity, the oldest data is evicted to make room. This prevents unbounded memory growth from chatty commands while still keeping recent output available for inspection.

Example

use kaish_kernel::scheduler::BoundedStream;

let stream = BoundedStream::new(100); // 100 byte max

stream.write(b"hello ").await;
stream.write(b"world").await;

let snapshot = stream.read().await;
assert_eq!(&snapshot, b"hello world");

Implementations

impl BoundedStream

pub fn new(max_size: usize) -> Self

Create a new bounded stream with the specified maximum size.

pub fn default_size() -> Self

Create a new bounded stream with the default max size (10MB).

pub async fn write(&self, data: &[u8])

Write data to the stream.

If the write would exceed capacity, the oldest data is evicted first. Writing to a closed stream is silently ignored.

pub async fn read(&self) -> Vec<u8>

Read a snapshot of the current buffer contents.

Returns a copy of all data currently in the buffer. The buffer is not modified.

pub async fn read_string(&self) -> String

Read the current buffer as a string (lossy UTF-8 conversion).

pub async fn close(&self)

Close the stream, indicating no more writes are expected.

Subsequent writes will be silently ignored.

pub async fn is_closed(&self) -> bool

Check if the stream has been closed.

pub async fn len(&self) -> usize

Get the current buffer size in bytes.

pub async fn is_empty(&self) -> bool

Check if the buffer is empty.

pub async fn has_overflowed(&self) -> bool

Whether this stream has ever evicted data due to overflow.

write silently drops the oldest bytes once the ring fills — this is the hot-path check capture sites use to detect that loss so they can surface it instead of reporting clean success (GH #191). Equivalent to stats().await.bytes_evicted > 0, but avoids building the full StreamStats when the caller only needs the boolean.

pub async fn changed_since(&self, seen_total_written: u64) -> StreamStats

Wait until this stream has written more than seen_total_written lifetime bytes, or has closed. Returns the stats that ended the wait, so the caller’s next call passes back stats.total_written.

This is the alternative to a poll loop for an embedder tailing a running job’s output. Pass 0 on the first call to wake on the first byte. A closed stream returns immediately, every time — the caller checks stats.closed and stops, rather than looping on a stream that can never change again.

The registration happens before the read, not after: Notify only reaches waiters that are already registered, so reading first would drop a write that landed in between and park until the next one.

pub async fn stats(&self) -> StreamStats

Get stream statistics.

Trait Implementations

impl Clone for BoundedStream

fn clone(&self) -> BoundedStream

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BoundedStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.