diff --git a/src/io/streams.rs b/src/io/streams.rs index bc26c12..d7139c1 100644 --- a/src/io/streams.rs +++ b/src/io/streams.rs @@ -3,6 +3,8 @@ use std::cell::OnceCell; use std::io::Result; use wasi::io::streams::{InputStream, OutputStream, StreamError}; +/// A wrapper for WASI's `InputStream` resource that provides implementations of `AsyncRead` and +/// `AsyncPollable`. #[derive(Debug)] pub struct AsyncInputStream { // Lazily initialized pollable, used for lifetime of stream to check readiness. @@ -12,12 +14,14 @@ pub struct AsyncInputStream { } impl AsyncInputStream { + /// Construct an `AsyncInputStream` from a WASI `InputStream` resource. pub fn new(stream: InputStream) -> Self { Self { subscription: OnceCell::new(), stream, } } + /// Await for read readiness. async fn ready(&self) { // Lazily initialize the AsyncPollable let subscription = self @@ -26,7 +30,8 @@ impl AsyncInputStream { // Wait on readiness subscription.wait_for().await; } - /// Like [`AsyncRead::read`], but doesn't require a `&mut self`. + /// Asynchronously read from the input stream. + /// This method is the same as [`AsyncRead::read`], but doesn't require a `&mut self`. pub async fn read(&self, buf: &mut [u8]) -> Result { let read = loop { self.ready().await; @@ -64,6 +69,8 @@ impl AsyncRead for AsyncInputStream { } } +/// A wrapper for WASI's `output-stream` resource that provides implementations of `AsyncWrite` and +/// `AsyncPollable`. #[derive(Debug)] pub struct AsyncOutputStream { // Lazily initialized pollable, used for lifetime of stream to check readiness. @@ -73,12 +80,14 @@ pub struct AsyncOutputStream { } impl AsyncOutputStream { + /// Construct an `AsyncOutputStream` from a WASI `OutputStream` resource. pub fn new(stream: OutputStream) -> Self { Self { subscription: OnceCell::new(), stream, } } + /// Await write readiness. async fn ready(&self) { // Lazily initialize the AsyncPollable let subscription = self @@ -87,7 +96,14 @@ impl AsyncOutputStream { // Wait on readiness subscription.wait_for().await; } - /// Like [`AsyncWrite::write`], but doesn't require a `&mut self`. + /// Asynchronously write to the output stream. This method is the same as + /// [`AsyncWrite::write`], but doesn't require a `&mut self`. + /// + /// Awaits for write readiness, and then performs at most one write to the + /// output stream. Returns how much of the argument `buf` was written, or + /// a `std::io::Error` indicating either an error returned by the stream write + /// using the debug string provided by the WASI error, or else that the, + /// indicated by `std::io::ErrorKind::ConnectionReset`. pub async fn write(&self, buf: &[u8]) -> Result { // Loops at most twice. loop { @@ -118,7 +134,17 @@ impl AsyncOutputStream { } } } - /// Like [`AsyncWrite::flush`], but doesn't require a `&mut self`. + /// Asyncronously flush the output stream. Initiates a flush, and then + /// awaits until the flush is complete and the output stream is ready for + /// writing again. + /// + /// This method is the same as [`AsyncWrite::flush`], but doesn't require + /// a `&mut self`. + /// + /// Fails with a `std::io::Error` indicating either an error returned by + /// the stream flush, using the debug string provided by the WASI error, + /// or else that the stream is closed, indicated by + /// `std::io::ErrorKind::ConnectionReset`. pub async fn flush(&self) -> Result<()> { match self.stream.flush() { Ok(()) => {