Trait embedded_io_async::Read
source · pub trait Read: ErrorType {
// Required method
async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>;
// Provided method
async fn read_exact(
&mut self,
buf: &mut [u8]
) -> Result<(), ReadExactError<Self::Error>> { ... }
}
Expand description
Async reader.
This trait is the embedded-io-async
equivalent of [std::io::Read
].
Required Methods§
sourceasync fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>
async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>
Read some bytes from this source into the specified buffer, returning how many bytes were read.
If no bytes are currently available to read, this function waits until at least one byte is available.
If bytes are available, a non-zero amount of bytes is read to the beginning of buf
, and the amount
is returned. It is not guaranteed that all available bytes are returned, it is possible for the
implementation to read an amount of bytes less than buf.len()
while there are more bytes immediately
available.
If the reader is at end-of-file (EOF), Ok(0)
is returned. There is no guarantee that a reader at EOF
will always be so in the future, for example a reader can stop being at EOF if another process appends
more bytes to the underlying file.
If buf.len() == 0
, read
returns without waiting, with either Ok(0)
or an error.
The Ok(0)
doesn’t indicate EOF, unlike when called with a non-empty buffer.
Implementations are encouraged to make this function side-effect-free on cancel (AKA “cancel-safe”), i.e.
guarantee that if you cancel (drop) a read()
future that hasn’t completed yet, the stream’s
state hasn’t changed (no bytes have been read).
This is not a requirement to allow implementations that read into the user’s buffer straight from the hardware with e.g. DMA.
Implementations should document whether they’re actually side-effect-free on cancel or not.
Provided Methods§
sourceasync fn read_exact(
&mut self,
buf: &mut [u8]
) -> Result<(), ReadExactError<Self::Error>>
async fn read_exact( &mut self, buf: &mut [u8] ) -> Result<(), ReadExactError<Self::Error>>
Read the exact number of bytes required to fill buf
.
This function calls read()
in a loop until exactly buf.len()
bytes have
been read, waiting if needed.
This function is not side-effect-free on cancel (AKA “cancel-safe”), i.e. if you cancel (drop) a returned future that hasn’t completed yet, some bytes might have already been read, which will get lost.
Object Safety§
Implementations on Foreign Types§
source§impl Read for &[u8]
impl Read for &[u8]
Read is implemented for &[u8]
by copying from the slice.
Note that reading updates the slice to point to the yet unread part. The slice will be empty when EOF is reached.