From c21f1d09de3a6a7bb4952f400919e936032b8ee2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Mi=C4=85sko?= Date: Sat, 11 Mar 2023 00:00:00 +0000 Subject: [PATCH] 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. --- library/std/src/io/mod.rs | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index b2b6d86134b..4b31c552eed 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -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 {