Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

Clarify zero-length read documentation for components (#12039)

Alex Crichtonedeee6e64b9e
diff --git a/crates/wasmtime/src/runtime/component/concurrent/futures_and_streams.rs b/crates/wasmtime/src/runtime/component/concurrent/futures_and_streams.rs
index aef06104b9..4ea8d48fa2 100644
--- a/crates/wasmtime/src/runtime/component/concurrent/futures_and_streams.rs
+++ b/crates/wasmtime/src/runtime/component/concurrent/futures_and_streams.rs
@@ -263,12 +263,16 @@ impl<'a, T, B> Destination<'a, T, B> {
/// This will return `Some(_)` if the reader is a guest; it will return
/// `None` if the reader is the host.
///
- /// Note that, if this returns `None(0)`, the producer must still attempt to
- /// produce at least one item if the value of `finish` passed to
- /// `StreamProducer::poll_produce` is false. In that case, the reader is
- /// effectively asking when the producer will be able to produce items
- /// without blocking (or reach a terminal state such as end-of-stream),
- /// meaning the next non-zero read must complete without blocking.
+ /// Note that this can return `Some(0)`. This means that the guest is
+ /// attempting to perform a zero-length read which typically means that it's
+ /// trying to wait for this stream to be ready-to-read but is not actually
+ /// ready to receive the items yet. The host in this case is allowed to
+ /// either block waiting for readiness or immediately complete the
+ /// operation. The guest is expected to handle both cases. Some more
+ /// discussion about this case can be found in the discussion of ["Stream
+ /// Readiness" in the component-model repo][docs].
+ ///
+ /// [docs]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Concurrency.md#stream-readiness
pub fn remaining(&self, mut store: impl AsContextMut) -> Option<usize> {
let transmit = store
.as_context_mut()
@@ -437,6 +441,21 @@ pub trait StreamProducer<D>: Send + 'static {
///
/// This will be called whenever the reader starts a read.
///
+ /// # Arguments
+ ///
+ /// * `self` - a `Pin`'d version of self to perform Rust-level
+ /// future-related operations on.
+ /// * `cx` - a Rust-related [`Context`] which is passed to other
+ /// future-related operations or used to acquire a waker.
+ /// * `store` - the Wasmtime store that this operation is happening within.
+ /// Used, for example, to consult the state `D` associated with the store.
+ /// * `destination` - the location that items are to be written to.
+ /// * `finish` - a flag indicating whether the host should strive to
+ /// immediately complete/cancel any pending operation. See below for more
+ /// details.
+ ///
+ /// # Behavior
+ ///
/// 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
@@ -449,59 +468,109 @@ pub trait StreamProducer<D>: Send + 'static {
/// 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:
+ /// # Zero-length reads
+ ///
+ /// This function may be called with a zero-length capacity buffer
+ /// (i.e. `Destination::remaining` returns `Some(0)`). This indicates that
+ /// the guest wants to wait to see if an item is ready without actually
+ /// reading the item. For example think of a UNIX `poll` function run on a
+ /// TCP stream, seeing if it's readable without actually reading it.
+ ///
+ /// In this situation the host is allowed to either return immediately or
+ /// wait for readiness. Note that waiting for readiness is not always
+ /// possible. For example it's impossible to test if a Rust-native `Future`
+ /// is ready without actually reading the item. Stream-specific
+ /// optimizations, such as testing if a TCP stream is readable, may be
+ /// possible however.
+ ///
+ /// For a zero-length read, the host is allowed to:
///
/// - 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.
+ /// 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. This is the best-case scenario of
+ /// fulfilling the guest's desire -- items aren't read/buffered but the
+ /// host is saying it's ready when the guest is.
+ ///
+ /// - Return `Poll::Ready(Ok(StreamResult::Completed))` without actually
+ /// testing for readiness. The guest doesn't know this yet, but the guest
+ /// will realize that zero-length reads won't work on this stream when a
+ /// subsequent nonzero read attempt is made which returns `Poll::Pending`
+ /// here.
///
- /// - Return `Poll::Pending` if the next call to `poll_produce` with
- /// non-zero capacity is likely to also return `Poll::Pending`.
+ /// - Return `Poll::Pending` if the host has performed necessary async work
+ /// to wait for this stream to be readable without actually reading
+ /// anything. This is also a best-case scenario where the host is letting
+ /// the guest know that nothing is ready yet. Later the zero-length read
+ /// will complete and then the guest will attempt a nonzero-length read to
+ /// actually read some bytes.
///
/// - 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.
+ /// `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. It is not
+ /// recommended to do this and it's better to return
+ /// `StreamResult::Completed` without buffering anything instead.
+ ///
+ /// For more discussion on zero-length reads see the [documentation in the
+ /// component-model repo itself][docs].
+ ///
+ /// [docs]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Concurrency.md#stream-readiness
+ ///
+ /// # Return
+ ///
+ /// This function can return a number of possible cases from this function:
+ ///
+ /// * `Poll::Pending` - this operation cannot complete at this time. The
+ /// Rust-level `Future::poll` contract applies here where a waker should
+ /// be stored from the `cx` argument and be arranged to receive a
+ /// notification when this implementation can make progress. For example
+ /// if you call `Future::poll` on a sub-future, that's enough. If items
+ /// were written to `destination` then a trap in the guest will be raised.
+ ///
+ /// Note that implementations should strive to avoid this return value
+ /// when `finish` is `true`. In such a situation the guest is attempting
+ /// to, for example, cancel a previous operation. By returning
+ /// `Poll::Pending` the guest will be blocked during the cancellation
+ /// request. If `finish` is `true` then `StreamResult::Cancelled` is
+ /// favored to indicate that no items were read. If a short read happened,
+ /// however, it's ok to return `StreamResult::Completed` indicating some
+ /// items were read.
+ ///
+ /// * `Poll::Ok(StreamResult::Completed)` - items, if applicable, were
+ /// written to the `destination`.
+ ///
+ /// * `Poll::Ok(StreamResult::Cancelled)` - used when `finish` is `true` and
+ /// the implementation was able to successfully cancel any async work that
+ /// a previous read kicked off, if any. The host should not buffer values
+ /// received after returning `Cancelled` because the guest will not be
+ /// aware of these values and the guest could close the stream after
+ /// cancelling a read. Hosts should only return `Cancelled` when there are
+ /// no more async operations in flight for a previous read.
+ ///
+ /// If items were written to `destination` then a trap in the guest will
+ /// be raised. If `finish` is `false` then this return value will raise a
+ /// trap in the guest.
+ ///
+ /// * `Poll::Ok(StreamResult::Dropped)` - end-of-stream marker, indicating
+ /// that this producer should not be polled again. Note that items may
+ /// still be written to `destination`.
+ ///
+ /// # Errors
+ ///
+ /// 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))`.
fn poll_produce<'a>(
self: Pin<&mut Self>,
cx: &mut Context<'_>,