read_buf_exact: on error, all read bytes are appended to the buffer

Guarantee that when `read_buf_exact` returns, all bytes read will be
appended to the buffer. Including the case when the operations fails.

The motivating use case are operations on a non-blocking reader. When
`read_buf_exact` fails with `ErrorKind::WouldBlock` error, the operation
can be resumed at a later time.
This commit is contained in:
Tomasz Miąsko 2023-03-11 00:00:00 +00:00
parent e350fe4e60
commit c21f1d09de

View File

@ -823,8 +823,22 @@ pub trait Read {
/// Read the exact number of bytes required to fill `cursor`.
///
/// This is equivalent to the [`read_exact`](Read::read_exact) method, except that it is passed a [`BorrowedCursor`] rather than `[u8]` to
/// allow use with uninitialized buffers.
/// This is similar to the [`read_exact`](Read::read_exact) method, except
/// that it is passed a [`BorrowedCursor`] rather than `[u8]` to allow use
/// with uninitialized buffers.
///
/// # Errors
///
/// If this function encounters an error of the kind [`ErrorKind::Interrupted`]
/// then the error is ignored and the operation will continue.
///
/// If this function encounters an "end of file" before completely filling
/// the buffer, it returns an error of the kind [`ErrorKind::UnexpectedEof`].
///
/// If any other read error is encountered then this function immediately
/// returns.
///
/// If this function returns an error, all bytes read will be appended to `cursor`.
#[unstable(feature = "read_buf", issue = "78485")]
fn read_buf_exact(&mut self, mut cursor: BorrowedCursor<'_>) -> Result<()> {
while cursor.capacity() > 0 {