Skip to content

fidius-guest::stream_marker

Rust

The fidius::Stream<T> server-streaming return marker (FIDIUS-I-0026, D4).

pub

Marker type a plugin interface uses to declare a server-streaming method:

#[fidius::plugin_interface(version = 1, buffer = PluginAllocated)]
pub trait Source: Send + Sync {
fn read(&self, config: String) -> fidius::Stream<Row>;
}

#[plugin_interface] recognises a return type whose final path segment is Stream<T> and, for that method:

  1. folds a !stream marker into the interface hash (so a streaming method can never be confused with a unary -> T method of the same name/args — a producer/consumer mismatch is rejected at load), and
  2. (Phase 1+) generates a host-side client method returning the runtime pull handle (fidius_host::ChunkStream).

The marker carries no data — the runtime representation of a stream is the host-side ChunkStream, not this type. It exists so the interface trait type-checks and so the macro has an explicit, unambiguous thing to detect (rather than guessing from impl Stream). T is the per-item type and follows the same wire/WitType rules as a unary return.

Argument-position Stream<T> (client-streaming / bidirectional) is rejected in v1.

Two forms (FIDIUS-I-0026)

  • Marker form (Stream::new): no items. Used purely to declare a streaming method in an interface trait — the Python path (Phase 1) never iterates it in Rust (its generator is bridged to a ChunkStream host-side).
  • Iterator-backed form (Stream::from_iter): a Rust WASM guest (Phase 2) returns real items. The macro-generated component resource pulls them one at a time via Stream::next_item to satisfy the WIT contract:
    resource <m>-stream { next: func() -> result<option<T>, plugin-error>; }
    <m>: func(args) -> own<<m>-stream>;
    some(item) = item, none = clean end, err = mid-stream error; dropping the resource runs the guest dtor = cancel (design decision D3).

pub

fn new() -> Self

The marker form — declares a streaming method without producing items. The interface/Python path uses this; it is never iterated in Rust.

Source
pub fn new() -> Self {
Self {
iter: None,
_marker: PhantomData,
}
}

pub

fn from_iter<I>(items: I) -> Self
where
I: IntoIterator<Item = T>,
I::IntoIter: Send + 'static,

Build a stream from any iterator — how a Rust WASM guest produces its items. The iterator must be Send + 'static so the host can drive the component resource across its pump thread.

Source
pub fn from_iter<I>(items: I) -> Self
where
I: IntoIterator<Item = T>,
I::IntoIter: Send + 'static,
{
Self {
iter: Some(Box::new(items.into_iter())),
_marker: PhantomData,
}
}

pub

fn next_item(&mut self) -> Option<T>

Advance the underlying iterator by one item. Driven by the macro-generated component resource’s next() (WS.2). Returns None for the marker form and at end of iteration.

Source
pub fn next_item(&mut self) -> Option<T> {
self.iter.as_mut().and_then(|it| it.next())
}