From 392fa46b6b6232ea54326ac0224e040b8e8e545f Mon Sep 17 00:00:00 2001 From: Roman Volosatovs Date: Fri, 8 Sep 2023 19:26:49 +0200 Subject: [PATCH 1/2] doc: document `HostOutputStream` Signed-off-by: Roman Volosatovs Co-authored-by: Pat Hickey --- crates/wasi/src/preview2/stream.rs | 49 +++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/crates/wasi/src/preview2/stream.rs b/crates/wasi/src/preview2/stream.rs index 4db8d39dfa05..4abe51c5276c 100644 --- a/crates/wasi/src/preview2/stream.rs +++ b/crates/wasi/src/preview2/stream.rs @@ -105,17 +105,56 @@ impl std::error::Error for OutputStreamError { /// A bytestream which can be written to. #[async_trait::async_trait] pub trait HostOutputStream: Send + Sync { - /// FIXME docs + /// Write bytes after obtaining a permit to write those bytes + /// Prior to calling [`write`](Self::write) + /// the caller must call [`write_ready`](Self::write_ready), + /// which resolves to a non-zero permit + /// + /// This method must never block. + /// [`write_ready`](Self::write_ready) permit indicates the maximum amount of bytes that are + /// permitted to be written in a single [`write`](Self::write) following the + /// [`write_ready`](Self::write_ready) resolution + /// + /// # Errors + /// + /// Returns an [OutputStreamError] if: + /// - stream is closed + /// - prior operation ([`write`](Self::write) or [`flush`](Self::flush)) failed + /// - caller performed an illegal operation (e.g. wrote more bytes than were permitted) fn write(&mut self, bytes: Bytes) -> Result<(), OutputStreamError>; - /// FIXME docs + /// Trigger a flush of any bytes buffered in this stream implementation. + /// + /// This method may be called at any time and must never block. + /// + /// After this method is called, [`write_ready`](Self::write_ready) must pend until flush is + /// complete. + /// When [`write_ready`](Self::write_ready) becomes ready after a flush, that guarantees that + /// all prior writes have been flushed from the implementation successfully, or that any error + /// associated with those writes is reported in the return value of [`flush`](Self::flush) or + /// [`write_ready`](Self::write_ready) + /// + /// # Errors + /// + /// Returns an [OutputStreamError] if: + /// - stream is closed + /// - prior operation ([`write`](Self::write) or [`flush`](Self::flush)) failed + /// - caller performed an illegal operation (e.g. wrote more bytes than were permitted) fn flush(&mut self) -> Result<(), OutputStreamError>; - /// FIXME docs + /// Returns a future, which: + /// - when pending, indicates 0 bytes are permitted for writing + /// - when ready, returns a non-zero number of bytes permitted to write + /// + /// # Errors + /// + /// Returns an [OutputStreamError] if: + /// - stream is closed + /// - prior operation ([`write`](Self::write) or [`flush`](Self::flush)) failed async fn write_ready(&mut self) -> Result; - /// Repeatedly write a byte to a stream. Important: this write must be - /// non-blocking! + /// Repeatedly write a byte to a stream. + /// Important: this write must be non-blocking! /// Returning an Err which downcasts to a [`StreamRuntimeError`] will be /// reported to Wasm as the empty error result. Otherwise, errors will trap. fn write_zeroes(&mut self, nelem: usize) -> Result<(), OutputStreamError> { From 937f9ec9432959f5fc91b55fb06b1a33ab1b37bd Mon Sep 17 00:00:00 2001 From: Roman Volosatovs Date: Fri, 8 Sep 2023 19:35:25 +0200 Subject: [PATCH 2/2] fix(wasi): fail when `MemoryOutputStream` buffer is full Signed-off-by: Roman Volosatovs --- crates/wasi/src/preview2/pipe.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/wasi/src/preview2/pipe.rs b/crates/wasi/src/preview2/pipe.rs index b6b886a12f17..e4b917956d58 100644 --- a/crates/wasi/src/preview2/pipe.rs +++ b/crates/wasi/src/preview2/pipe.rs @@ -98,7 +98,8 @@ impl HostOutputStream for MemoryOutputPipe { if consumed < self.capacity { Ok(self.capacity - consumed) } else { - Ok(0) + // Since the buffer is full, no more bytes will ever be written + Err(OutputStreamError::Closed) } } }