1 #![unstable(feature = "read_buf", issue = "78485")]
6 use crate::fmt::{self, Debug, Formatter};
7 use crate::io::{Result, Write};
8 use crate::mem::{self, MaybeUninit};
11 /// A borrowed byte buffer which is incrementally filled and initialized.
13 /// This type is a sort of "double cursor". It tracks three regions in the buffer: a region at the beginning of the
14 /// buffer that has been logically filled with data, a region that has been initialized at some point but not yet
15 /// logically filled, and a region at the end that is fully uninitialized. The filled region is guaranteed to be a
16 /// subset of the initialized region.
18 /// In summary, the contents of the buffer can be visualized as:
21 /// [ filled | unfilled ]
22 /// [ initialized | uninitialized ]
25 /// A `BorrowedBuf` is created around some existing data (or capacity for data) via a unique reference
26 /// (`&mut`). The `BorrowedBuf` can be configured (e.g., using `clear` or `set_init`), but cannot be
27 /// directly written. To write into the buffer, use `unfilled` to create a `BorrowedCursor`. The cursor
28 /// has write-only access to the unfilled portion of the buffer (you can think of it as a
29 /// write-only iterator).
31 /// The lifetime `'data` is a bound on the lifetime of the underlying data.
32 pub struct BorrowedBuf<'data> {
33 /// The buffer's underlying data.
34 buf: &'data mut [MaybeUninit<u8>],
35 /// The length of `self.buf` which is known to be filled.
37 /// The length of `self.buf` which is known to be initialized.
41 impl Debug for BorrowedBuf<'_> {
42 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
43 f.debug_struct("BorrowedBuf")
44 .field("init", &self.init)
45 .field("filled", &self.filled)
46 .field("capacity", &self.capacity())
51 /// Create a new `BorrowedBuf` from a fully initialized slice.
52 impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data> {
54 fn from(slice: &'data mut [u8]) -> BorrowedBuf<'data> {
55 let len = slice.len();
58 // SAFETY: initialized data never becoming uninitialized is an invariant of BorrowedBuf
59 buf: unsafe { (slice as *mut [u8]).as_uninit_slice_mut().unwrap() },
66 /// Create a new `BorrowedBuf` from an uninitialized buffer.
68 /// Use `set_init` if part of the buffer is known to be already initialized.
69 impl<'data> From<&'data mut [MaybeUninit<u8>]> for BorrowedBuf<'data> {
71 fn from(buf: &'data mut [MaybeUninit<u8>]) -> BorrowedBuf<'data> {
72 BorrowedBuf { buf, filled: 0, init: 0 }
76 impl<'data> BorrowedBuf<'data> {
77 /// Returns the total capacity of the buffer.
79 pub fn capacity(&self) -> usize {
83 /// Returns the length of the filled part of the buffer.
85 pub fn len(&self) -> usize {
89 /// Returns the length of the initialized part of the buffer.
91 pub fn init_len(&self) -> usize {
95 /// Returns a shared reference to the filled portion of the buffer.
97 pub fn filled(&self) -> &[u8] {
98 // SAFETY: We only slice the filled part of the buffer, which is always valid
99 unsafe { MaybeUninit::slice_assume_init_ref(&self.buf[0..self.filled]) }
102 /// Returns a cursor over the unfilled part of the buffer.
104 pub fn unfilled<'this>(&'this mut self) -> BorrowedCursor<'this> {
107 // SAFETY: we never assign into `BorrowedCursor::buf`, so treating its
108 // lifetime covariantly is safe.
110 mem::transmute::<&'this mut BorrowedBuf<'data>, &'this mut BorrowedBuf<'this>>(self)
115 /// Clears the buffer, resetting the filled region to empty.
117 /// The number of initialized bytes is not changed, and the contents of the buffer are not modified.
119 pub fn clear(&mut self) -> &mut Self {
124 /// Asserts that the first `n` bytes of the buffer are initialized.
126 /// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when called with fewer
127 /// bytes than are already known to be initialized.
131 /// The caller must ensure that the first `n` unfilled bytes of the buffer have already been initialized.
133 pub unsafe fn set_init(&mut self, n: usize) -> &mut Self {
134 self.init = cmp::max(self.init, n);
139 /// A writeable view of the unfilled portion of a [`BorrowedBuf`](BorrowedBuf).
141 /// Provides access to the initialized and uninitialized parts of the underlying `BorrowedBuf`.
142 /// Data can be written directly to the cursor by using [`append`](BorrowedCursor::append) or
143 /// indirectly by getting a slice of part or all of the cursor and writing into the slice. In the
144 /// indirect case, the caller must call [`advance`](BorrowedCursor::advance) after writing to inform
145 /// the cursor how many bytes have been written.
147 /// Once data is written to the cursor, it becomes part of the filled portion of the underlying
148 /// `BorrowedBuf` and can no longer be accessed or re-written by the cursor. I.e., the cursor tracks
149 /// the unfilled part of the underlying `BorrowedBuf`.
151 /// The lifetime `'a` is a bound on the lifetime of the underlying buffer (which means it is a bound
152 /// on the data in that buffer by transitivity).
154 pub struct BorrowedCursor<'a> {
155 /// The underlying buffer.
156 // Safety invariant: we treat the type of buf as covariant in the lifetime of `BorrowedBuf` when
157 // we create a `BorrowedCursor`. This is only safe if we never replace `buf` by assigning into
158 // it, so don't do that!
159 buf: &'a mut BorrowedBuf<'a>,
160 /// The length of the filled portion of the underlying buffer at the time of the cursor's
165 impl<'a> BorrowedCursor<'a> {
166 /// Reborrow this cursor by cloning it with a smaller lifetime.
168 /// Since a cursor maintains unique access to its underlying buffer, the borrowed cursor is
169 /// not accessible while the new cursor exists.
171 pub fn reborrow<'this>(&'this mut self) -> BorrowedCursor<'this> {
173 // SAFETY: we never assign into `BorrowedCursor::buf`, so treating its
174 // lifetime covariantly is safe.
176 mem::transmute::<&'this mut BorrowedBuf<'a>, &'this mut BorrowedBuf<'this>>(
184 /// Returns the available space in the cursor.
186 pub fn capacity(&self) -> usize {
187 self.buf.capacity() - self.buf.filled
190 /// Returns the number of bytes written to this cursor since it was created from a `BorrowedBuf`.
192 /// Note that if this cursor is a reborrowed clone of another, then the count returned is the
193 /// count written via either cursor, not the count since the cursor was reborrowed.
195 pub fn written(&self) -> usize {
196 self.buf.filled - self.start
199 /// Returns a shared reference to the initialized portion of the cursor.
201 pub fn init_ref(&self) -> &[u8] {
202 // SAFETY: We only slice the initialized part of the buffer, which is always valid
203 unsafe { MaybeUninit::slice_assume_init_ref(&self.buf.buf[self.buf.filled..self.buf.init]) }
206 /// Returns a mutable reference to the initialized portion of the cursor.
208 pub fn init_mut(&mut self) -> &mut [u8] {
209 // SAFETY: We only slice the initialized part of the buffer, which is always valid
211 MaybeUninit::slice_assume_init_mut(&mut self.buf.buf[self.buf.filled..self.buf.init])
215 /// Returns a mutable reference to the uninitialized part of the cursor.
217 /// It is safe to uninitialize any of these bytes.
219 pub fn uninit_mut(&mut self) -> &mut [MaybeUninit<u8>] {
220 &mut self.buf.buf[self.buf.init..]
223 /// Returns a mutable reference to the whole cursor.
227 /// The caller must not uninitialize any bytes in the initialized portion of the cursor.
229 pub unsafe fn as_mut(&mut self) -> &mut [MaybeUninit<u8>] {
230 &mut self.buf.buf[self.buf.filled..]
233 /// Advance the cursor by asserting that `n` bytes have been filled.
235 /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be
236 /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements
237 /// and its unfilled portion (and the capacity of this cursor) shrinks by `n` elements.
241 /// The caller must ensure that the first `n` bytes of the cursor have been properly
244 pub unsafe fn advance(&mut self, n: usize) -> &mut Self {
245 self.buf.filled += n;
246 self.buf.init = cmp::max(self.buf.init, self.buf.filled);
250 /// Initializes all bytes in the cursor.
252 pub fn ensure_init(&mut self) -> &mut Self {
253 let uninit = self.uninit_mut();
254 // SAFETY: 0 is a valid value for MaybeUninit<u8> and the length matches the allocation
255 // since it is comes from a slice reference.
257 ptr::write_bytes(uninit.as_mut_ptr(), 0, uninit.len());
259 self.buf.init = self.buf.capacity();
264 /// Asserts that the first `n` unfilled bytes of the cursor are initialized.
266 /// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when
267 /// called with fewer bytes than are already known to be initialized.
271 /// The caller must ensure that the first `n` bytes of the buffer have already been initialized.
273 pub unsafe fn set_init(&mut self, n: usize) -> &mut Self {
274 self.buf.init = cmp::max(self.buf.init, self.buf.filled + n);
278 /// Appends data to the cursor, advancing position within its buffer.
282 /// Panics if `self.capacity()` is less than `buf.len()`.
284 pub fn append(&mut self, buf: &[u8]) {
285 assert!(self.capacity() >= buf.len());
287 // SAFETY: we do not de-initialize any of the elements of the slice
289 MaybeUninit::write_slice(&mut self.as_mut()[..buf.len()], buf);
292 // SAFETY: We just added the entire contents of buf to the filled section.
294 self.set_init(buf.len());
296 self.buf.filled += buf.len();
300 impl<'a> Write for BorrowedCursor<'a> {
301 fn write(&mut self, buf: &[u8]) -> Result<usize> {
306 fn flush(&mut self) -> Result<()> {