Trait StreamProducer

pub trait StreamProducer<D>: Send + 'static {
    type Item;
    type Buffer: WriteBuffer<Self::Item> + Default;

    // Required method
    fn poll_produce<'a>(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        store: StoreContextMut<'a, D>,
        destination: Destination<'a, Self::Item, Self::Buffer>,
        finish: bool,
    ) -> Poll<Result<StreamResult>>;
}

Available on crate features runtime and component-model and component-model-async only.

Represents the host-owned write end of a stream.

Required Associated Types

type Item

The payload type of this stream.

type Buffer: WriteBuffer<Self::Item> + Default

The WriteBuffer type to use when delivering items.

Required Methods

fn poll_produce<'a>( self: Pin<&mut Self>, cx: &mut Context<'_>, store: StoreContextMut<'a, D>, destination: Destination<'a, Self::Item, Self::Buffer>, finish: bool, ) -> Poll<Result<StreamResult>>

Handle a host- or guest-initiated read by delivering zero or more items to the specified destination.

This will be called whenever the reader starts a read.

If the implementation is able to produce one or more items immediately, it should write them to destination and return either Poll::Ready(Ok(StreamResult::Completed)) if it expects to produce more items, or Poll::Ready(Ok(StreamResult::Dropped)) if it cannot produce any more items.

If the implementation is unable to produce any items immediately, but expects to do so later, and finish is false, it should store the waker from cx for later and return Poll::Pending without writing anything to destination. Later, it should alert the waker when either the items arrive, the stream has ended, or an error occurs.

If the implementation is unable to produce any items immediately, but expects to do so later, and finish is true, it should, if possible, return Poll::Ready(Ok(StreamResult::Cancelled)) immediately without writing anything to destination. However, that might not be possible if an earlier call to poll_produce kicked off an asynchronous operation which needs to be completed (and possibly interrupted) gracefully, in which case the implementation may return Poll::Pending and later alert the waker as described above. In other words, when finish is true, the implementation should prioritize returning a result to the reader (even if no items can be produced) rather than wait indefinitely for at least one item to arrive.

In all of the above cases, the implementation may alternatively choose to return Err(_) to indicate an unrecoverable error. This will cause the guest (if any) to trap and render the component instance (if any) unusable. The implementation should report errors that are recoverable by other means (e.g. by writing to a future) and return Poll::Ready(Ok(StreamResult::Dropped)).

Note that the implementation should never return Poll::Pending after writing one or more items to destination; if it does, the caller will trap as if Err(_) was returned. Conversely, it should only return Poll::Ready(Ok(StreamResult::Cancelled)) without writing any items to destination if called with finish set to true. If it does so when finish is false, the caller will trap. Additionally, it should only return Poll::Ready(Ok(StreamResult::Completed)) after writing at least one item to destination if it has capacity to accept that item; otherwise, the caller will trap.

If more items are written to destination than the reader has immediate capacity to accept, they will be retained in memory by the caller and used to satisfy future reads, in which case poll_produce will only be called again once all those items have been delivered.

If this function is called with zero capacity (i.e. Destination::remaining returns Some(0)), the implementation should either:

• Return Poll::Ready(Ok(StreamResult::Completed)) without writing anything if it expects to be able to produce items immediately (i.e. without first returning Poll::Pending) the next time poll_produce is called with non-zero capacity or if that cannot be reliably determined.

• Return Poll::Pending if the next call to poll_produce with non-zero capacity is likely to also return Poll::Pending.

• Return Poll::Ready(Ok(StreamResult::Completed)) after calling Destination::set_buffer with one more more items. Note, however, that this creates the hazard that the items will never be received by the guest if it decides not to do another non-zero-length read before closing the stream. Moreover, if Self::Item is e.g. a Resource<_>, they may end up leaking in that scenario.

Implementors