Struct StreamHandle 

pub struct StreamHandle { /* private fields */ }

Live handle to a memory stream source, sink, or pipeline.

A StreamHandle is a cheap, cloneable reference (an Arc inner) to one of four kinds of memory endpoint: a pull source, a PCM sink, a MIDI sink, or a pipeline that connects a source to an optional sink. Reads (StreamHandle::next_packet), writes (StreamHandle::write_packet), and whole-stream runs (StreamHandle::run) are dispatched on the handle kind and fail closed when invoked on an endpoint that does not support them.

Implementations

impl StreamHandle

pub fn source(metadata: StreamMetadata, stream: Arc<StreamValue>) -> Self

Builds a pull-source handle backed by the given stream value.

pub fn pcm_sink(metadata: StreamMetadata, spec: PcmSpec) -> Self

Builds a PCM sink handle that validates writes against spec.

pub fn midi_sink(metadata: StreamMetadata, tpq: u16) -> Self

Builds a MIDI sink handle that validates writes against tpq.

pub fn pipeline( source: StreamHandle, sink: Option<StreamHandle>, ) -> Result<Self>

Builds a pipeline handle from a source-like handle and optional sink.

Errors

Returns an error when source is not source-like, or when sink is present but is not a sink handle.

pub fn metadata(&self) -> &StreamMetadata

Returns the stream metadata describing this handle.

pub fn is_sink(&self) -> bool

Returns true when this handle is a PCM or MIDI sink.

pub fn is_pipeline_with_sink(&self) -> bool

Returns true when this handle is a pipeline that drives a sink.

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

Pulls the next packet from a source or pipeline source.

Returns Ok(None) once the stream is exhausted.

Errors

Returns an error when called on a sink handle, or when the underlying source fails to produce the next packet.

pub fn write_packet(&self, packet: StreamPacket) -> Result<()>

Writes one packet into a PCM or MIDI sink.

Errors

Returns an error when called on a non-sink handle, when the packet media does not match the sink, or when the packet fails sink validation.

pub fn run(&self) -> Result<RunReport>

Drains a source or pipeline to completion, returning a RunReport.

For a pipeline with a sink, every pulled packet is written into the sink and the sink is closed at the end.

Errors

Returns an error when called on a bare sink handle, or when reading or writing a packet fails.

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

Cancels the stream, marking sources and sinks closed and cancelled.

Cancelling a pipeline cancels its source and sink in turn.

Errors

Returns an error when a sink lock is poisoned or a source cancel fails.

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

Returns a snapshot of the stream’s runtime statistics.

Errors

Returns an error when a sink lock is poisoned or a source cannot report its statistics.

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

Returns true when the stream has no more work to do.

A pipeline is done only when both its source and its sink are done.

Errors

Returns an error when a sink lock is poisoned or a source cannot report its completion state.

pub fn sink_packets(&self) -> Result<Vec<StreamPacket>>

Returns a copy of the packets accumulated by a sink handle.

Errors

Returns an error when called on a non-sink handle or when the sink lock is poisoned.

pub fn graph_lisp_expr(&self) -> Expr

Renders this handle as a stream graph expression.

A pipeline renders as a stream/pipe call over its source and optional sink ids; a bare source or sink renders as its id string.

Trait Implementations

impl Clone for StreamHandle

fn clone(&self) -> StreamHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Object for StreamHandle

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 StreamHandle

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

Class object this value belongs to; defaults to nil.

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_sequence(&self) -> Option<&dyn Sequence>

Sequence view, if the object is a sequence.

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.