Struct StreamValue 

pub struct StreamValue { /* private fields */ }

The runtime-visible stream value: metadata plus a live spine.

A StreamValue is the homogeneous stream object the runtime passes around. It is a non-citizen live handle (it is not serialized directly; consumers reconstruct the stream/Packet and stream/Metadata descriptors and realize them separately). Build a finite, replayable stream with StreamValue::pull or a producer-fed stream with StreamValue::push, then drive it through the base combinators (next_packet, peek_packet, take_packets, run_events, cancel, is_done).

As a kernel Object it presents as a Sequence, so it interoperates with sequence-consuming operations directly.

Implementations

impl StreamValue

pub fn pull(metadata: StreamMetadata, items: Vec<StreamItem>) -> Self

Builds a pull stream that yields the given pre-built items in order.

A pull stream is finite and self-draining: it serves items until exhausted, then reports done. It rejects pushed packets.

pub fn push(metadata: StreamMetadata) -> Self

Builds a push stream fed by an external producer.

The stream starts empty; producers call StreamValue::push_packet to enqueue items under the buffer policy carried by metadata, and consumers pull them out.

pub fn metadata(&self) -> &StreamMetadata

Returns the stream’s immutable metadata.

pub fn publish_claims(&self, cx: &mut Cx, subject: Ref) -> Result<()>

Publishes this stream’s metadata as claims about subject into cx.

pub fn push_packet(&self, item: StreamItem) -> Result<PushResult>

Pushes a packet into a push stream, returning the backpressure outcome.

Returns an error when called on a pull stream, which accepts no input.

pub fn close_push(&self) -> Result<()>

Closes the stream to further input, leaving buffered items to drain.

pub fn next_packet(&self) -> Result<Option<StreamItem>>

Pulls the next packet, or None if the stream is currently empty or exhausted.

Does not block; on a push stream an empty-but-open queue yields None.

pub fn next_packet_timeout( &self, timeout: Duration, ) -> Result<Option<StreamItem>>

Pulls the next packet, blocking up to timeout for one to arrive.

On a pull stream this is equivalent to StreamValue::next_packet; on a push stream it waits for a producer up to timeout before yielding None.

pub fn peek_packet(&self) -> Result<Option<StreamItem>>

Returns a clone of the next packet without consuming it.

pub fn is_done(&self) -> Result<bool>

Reports whether the stream is exhausted and will yield no more packets.

pub fn take_packets(&self, limit: usize) -> Result<Vec<StreamItem>>

Pulls up to limit packets, stopping early when the stream runs dry.

pub fn run_events( &self, cx: &mut Cx, run: Ref, start_seq: u64, ) -> Result<Vec<Event>>

Drains the stream into a vector of sequenced packet events.

Pulls every currently available packet, emitting one packet Event per item numbered from start_seq, and appends a terminal done event if the stream is exhausted. Events are attributed to run.

pub fn cancel(&self) -> Result<()>

Cancels the stream: closes it and discards any buffered packets.

pub fn stats(&self) -> Result<StreamStats>

Returns a snapshot of the stream’s lifetime StreamStats.

pub fn queue_depth(&self) -> Result<usize>

Returns the number of packets currently buffered in the spine.

pub fn event_source( self: &Arc<Self>, run: Ref, start_seq: u64, ) -> Arc<StreamEventSource>

Builds an StreamEventSource that feeds this stream’s packets into the run ledger as sequenced events numbered from start_seq.

Trait Implementations

impl Object for StreamValue

fn display(&self, _cx: &mut Cx) -> Result<String>

Render the object as a human-readable display string.

fn as_any(&self) -> &dyn Any

Expose the object for Rust downcasting.

fn header(&self) -> &ObjectHeader

Identity and trust header for the object; defaults to the shared anonymous header.

fn op(&self, _key: &OpKey) -> Option<&dyn Op>

Resolve the operation registered under key, if any.

fn claims( &self, _cx: &mut Cx, _pattern: &ClaimPattern, _sink: &mut dyn ClaimSink, ) -> Result<(), Error>

Emit the object’s claims matching pattern into sink.

fn snapshot(&self, _cx: &mut Cx) -> Result<Option<Datum>, Error>

Optional content-addressable snapshot of the object’s state.

impl ObjectCompat for StreamValue

fn class(&self, cx: &mut Cx) -> Result<ClassRef>

Class object this value belongs to; defaults to nil.

fn as_sequence(&self) -> Option<&dyn Sequence>

Sequence view, if the object is a sequence.

fn as_callable(&self) -> Option<&dyn Callable>

Callable view, if the object can be invoked.

fn as_class(&self) -> Option<&dyn Class>

Class view, if the object is a class.

fn as_shape(&self) -> Option<&dyn Shape>

Shape view, if the object is a shape.

fn as_object_encoder(&self) -> Option<&dyn ObjectEncode>

Object-encoder view, if the object encodes other objects.

fn as_read_constructor(&self) -> Option<&dyn ReadConstructor>

Read-constructor view, if the object decodes data forms.

fn as_number_domain(&self) -> Option<&(dyn NumberDomain + 'static)>

Number-domain view, if the object is a number domain.

fn as_number_value(&self) -> Option<&dyn NumberValue>

Number-value view, if the object is a domain number.

fn as_eval_fabric(&self) -> Option<&dyn EvalFabric>

Eval-fabric view, if the object is a distributed eval surface.

fn as_stream(&self) -> Option<&dyn Stream>

Stream view, if the object is a stream.

fn as_thunk(&self) -> Option<&dyn Thunk>

Thunk view, if the object is a deferred computation.

fn as_list(&self) -> Option<&(dyn ListValue + 'static)>

List view, if the object is a list value.

fn as_table_impl(&self) -> Option<&(dyn Table + 'static)>

Table-implementation view, if the object is a table.

fn as_dir(&self) -> Option<&(dyn Dir + 'static)>

Directory view, if the object is a directory.

fn as_expr(&self, cx: &mut Cx) -> Result<Expr, Error>

Expression form of the object; defaults to an opaque extension node.

fn truth(&self, _cx: &mut Cx) -> Result<bool, Error>

Truthiness of the object; defaults to true.

fn publish_shape_satisfaction_claims( &self, _cx: &mut Cx, _shape: &Ref, ) -> Result<bool, Error>

Publish claims asserting that the object satisfies shape; returns whether any were published.

fn as_table(&self, cx: &mut Cx) -> Result<Value, Error>

Project the object into a table value; the default exposes its display.

impl Sequence for StreamValue

fn next_item(&self, cx: &mut Cx) -> Result<Option<SequenceItem>>

Pulls the next item, or Ok(None) once exhausted.

fn close(&self, _cx: &mut Cx) -> Result<()>

Releases resources backing the sequence; idempotent by default.

fn peek_item(&self, cx: &mut Cx) -> Result<Option<SequenceItem>>

Peeks the next item without consuming it; unsupported by default.

fn is_done(&self, _cx: &mut Cx) -> Result<bool>

Whether the sequence is known to be exhausted; false by default.