1#![unstable(feature = "core_io_borrowed_buf", issue = "117693")]
2
3use crate::fmt::{self, Debug, Formatter};
4use crate::mem::{self, MaybeUninit};
5use crate::{cmp, ptr};
6
7/// A borrowed byte buffer which is incrementally filled and initialized.
8///
9/// This type is a sort of "double cursor". It tracks three regions in the buffer: a region at the beginning of the
10/// buffer that has been logically filled with data, a region that has been initialized at some point but not yet
11/// logically filled, and a region at the end that is fully uninitialized. The filled region is guaranteed to be a
12/// subset of the initialized region.
13///
14/// In summary, the contents of the buffer can be visualized as:
15/// ```not_rust
16/// [ capacity ]
17/// [ filled | unfilled ]
18/// [ initialized | uninitialized ]
19/// ```
20///
21/// A `BorrowedBuf` is created around some existing data (or capacity for data) via a unique reference
22/// (`&mut`). The `BorrowedBuf` can be configured (e.g., using `clear` or `set_init`), but cannot be
23/// directly written. To write into the buffer, use `unfilled` to create a `BorrowedCursor`. The cursor
24/// has write-only access to the unfilled portion of the buffer (you can think of it as a
25/// write-only iterator).
26///
27/// The lifetime `'data` is a bound on the lifetime of the underlying data.
28pub struct BorrowedBuf<'data> {
29 /// The buffer's underlying data.
30 buf: &'data mut [MaybeUninit<u8>],
31 /// The length of `self.buf` which is known to be filled.
32 filled: usize,
33 /// The length of `self.buf` which is known to be initialized.
34 init: usize,
35}
36
37impl Debug for BorrowedBuf<'_> {
38 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
39 f&mut DebugStruct<'_, '_>.debug_struct("BorrowedBuf")
40 .field("init", &self.init)
41 .field("filled", &self.filled)
42 .field(name:"capacity", &self.capacity())
43 .finish()
44 }
45}
46
47/// Creates a new `BorrowedBuf` from a fully initialized slice.
48impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data> {
49 #[inline]
50 fn from(slice: &'data mut [u8]) -> BorrowedBuf<'data> {
51 let len: usize = slice.len();
52
53 BorrowedBuf {
54 // SAFETY: initialized data never becoming uninitialized is an invariant of BorrowedBuf
55 buf: unsafe { (slice as *mut [u8]).as_uninit_slice_mut().unwrap() },
56 filled: 0,
57 init: len,
58 }
59 }
60}
61
62/// Creates a new `BorrowedBuf` from an uninitialized buffer.
63///
64/// Use `set_init` if part of the buffer is known to be already initialized.
65impl<'data> From<&'data mut [MaybeUninit<u8>]> for BorrowedBuf<'data> {
66 #[inline]
67 fn from(buf: &'data mut [MaybeUninit<u8>]) -> BorrowedBuf<'data> {
68 BorrowedBuf { buf, filled: 0, init: 0 }
69 }
70}
71
72/// Creates a new `BorrowedBuf` from a cursor.
73///
74/// Use `BorrowedCursor::with_unfilled_buf` instead for a safer alternative.
75impl<'data> From<BorrowedCursor<'data>> for BorrowedBuf<'data> {
76 #[inline]
77 fn from(mut buf: BorrowedCursor<'data>) -> BorrowedBuf<'data> {
78 let init: usize = buf.init_mut().len();
79 BorrowedBuf {
80 // SAFETY: no initialized byte is ever uninitialized as per
81 // `BorrowedBuf`'s invariant
82 buf: unsafe { buf.buf.buf.get_unchecked_mut(index:buf.buf.filled..) },
83 filled: 0,
84 init,
85 }
86 }
87}
88
89impl<'data> BorrowedBuf<'data> {
90 /// Returns the total capacity of the buffer.
91 #[inline]
92 pub fn capacity(&self) -> usize {
93 self.buf.len()
94 }
95
96 /// Returns the length of the filled part of the buffer.
97 #[inline]
98 pub fn len(&self) -> usize {
99 self.filled
100 }
101
102 /// Returns the length of the initialized part of the buffer.
103 #[inline]
104 pub fn init_len(&self) -> usize {
105 self.init
106 }
107
108 /// Returns a shared reference to the filled portion of the buffer.
109 #[inline]
110 pub fn filled(&self) -> &[u8] {
111 // SAFETY: We only slice the filled part of the buffer, which is always valid
112 unsafe {
113 let buf = self.buf.get_unchecked(..self.filled);
114 buf.assume_init_ref()
115 }
116 }
117
118 /// Returns a mutable reference to the filled portion of the buffer.
119 #[inline]
120 pub fn filled_mut(&mut self) -> &mut [u8] {
121 // SAFETY: We only slice the filled part of the buffer, which is always valid
122 unsafe {
123 let buf = self.buf.get_unchecked_mut(..self.filled);
124 buf.assume_init_mut()
125 }
126 }
127
128 /// Returns a shared reference to the filled portion of the buffer with its original lifetime.
129 #[inline]
130 pub fn into_filled(self) -> &'data [u8] {
131 // SAFETY: We only slice the filled part of the buffer, which is always valid
132 unsafe {
133 let buf = self.buf.get_unchecked(..self.filled);
134 buf.assume_init_ref()
135 }
136 }
137
138 /// Returns a mutable reference to the filled portion of the buffer with its original lifetime.
139 #[inline]
140 pub fn into_filled_mut(self) -> &'data mut [u8] {
141 // SAFETY: We only slice the filled part of the buffer, which is always valid
142 unsafe {
143 let buf = self.buf.get_unchecked_mut(..self.filled);
144 buf.assume_init_mut()
145 }
146 }
147
148 /// Returns a cursor over the unfilled part of the buffer.
149 #[inline]
150 pub fn unfilled<'this>(&'this mut self) -> BorrowedCursor<'this> {
151 BorrowedCursor {
152 // SAFETY: we never assign into `BorrowedCursor::buf`, so treating its
153 // lifetime covariantly is safe.
154 buf: unsafe {
155 mem::transmute::<&'this mut BorrowedBuf<'data>, &'this mut BorrowedBuf<'this>>(self)
156 },
157 }
158 }
159
160 /// Clears the buffer, resetting the filled region to empty.
161 ///
162 /// The number of initialized bytes is not changed, and the contents of the buffer are not modified.
163 #[inline]
164 pub fn clear(&mut self) -> &mut Self {
165 self.filled = 0;
166 self
167 }
168
169 /// Asserts that the first `n` bytes of the buffer are initialized.
170 ///
171 /// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when called with fewer
172 /// bytes than are already known to be initialized.
173 ///
174 /// # Safety
175 ///
176 /// The caller must ensure that the first `n` unfilled bytes of the buffer have already been initialized.
177 #[inline]
178 pub unsafe fn set_init(&mut self, n: usize) -> &mut Self {
179 self.init = cmp::max(self.init, n);
180 self
181 }
182}
183
184/// A writeable view of the unfilled portion of a [`BorrowedBuf`].
185///
186/// The unfilled portion consists of an initialized and an uninitialized part; see [`BorrowedBuf`]
187/// for details.
188///
189/// Data can be written directly to the cursor by using [`append`](BorrowedCursor::append) or
190/// indirectly by getting a slice of part or all of the cursor and writing into the slice. In the
191/// indirect case, the caller must call [`advance`](BorrowedCursor::advance) after writing to inform
192/// the cursor how many bytes have been written.
193///
194/// Once data is written to the cursor, it becomes part of the filled portion of the underlying
195/// `BorrowedBuf` and can no longer be accessed or re-written by the cursor. I.e., the cursor tracks
196/// the unfilled part of the underlying `BorrowedBuf`.
197///
198/// The lifetime `'a` is a bound on the lifetime of the underlying buffer (which means it is a bound
199/// on the data in that buffer by transitivity).
200#[derive(Debug)]
201pub struct BorrowedCursor<'a> {
202 /// The underlying buffer.
203 // Safety invariant: we treat the type of buf as covariant in the lifetime of `BorrowedBuf` when
204 // we create a `BorrowedCursor`. This is only safe if we never replace `buf` by assigning into
205 // it, so don't do that!
206 buf: &'a mut BorrowedBuf<'a>,
207}
208
209impl<'a> BorrowedCursor<'a> {
210 /// Reborrows this cursor by cloning it with a smaller lifetime.
211 ///
212 /// Since a cursor maintains unique access to its underlying buffer, the borrowed cursor is
213 /// not accessible while the new cursor exists.
214 #[inline]
215 pub fn reborrow<'this>(&'this mut self) -> BorrowedCursor<'this> {
216 BorrowedCursor {
217 // SAFETY: we never assign into `BorrowedCursor::buf`, so treating its
218 // lifetime covariantly is safe.
219 buf: unsafe {
220 mem::transmute::<&'this mut BorrowedBuf<'a>, &'this mut BorrowedBuf<'this>>(
221 self.buf,
222 )
223 },
224 }
225 }
226
227 /// Returns the available space in the cursor.
228 #[inline]
229 pub fn capacity(&self) -> usize {
230 self.buf.capacity() - self.buf.filled
231 }
232
233 /// Returns the number of bytes written to the `BorrowedBuf` this cursor was created from.
234 ///
235 /// In particular, the count returned is shared by all reborrows of the cursor.
236 #[inline]
237 pub fn written(&self) -> usize {
238 self.buf.filled
239 }
240
241 /// Returns a mutable reference to the initialized portion of the cursor.
242 #[inline]
243 pub fn init_mut(&mut self) -> &mut [u8] {
244 // SAFETY: We only slice the initialized part of the buffer, which is always valid
245 unsafe {
246 let buf = self.buf.buf.get_unchecked_mut(self.buf.filled..self.buf.init);
247 buf.assume_init_mut()
248 }
249 }
250
251 /// Returns a mutable reference to the whole cursor.
252 ///
253 /// # Safety
254 ///
255 /// The caller must not uninitialize any bytes in the initialized portion of the cursor.
256 #[inline]
257 pub unsafe fn as_mut(&mut self) -> &mut [MaybeUninit<u8>] {
258 // SAFETY: always in bounds
259 unsafe { self.buf.buf.get_unchecked_mut(self.buf.filled..) }
260 }
261
262 /// Advances the cursor by asserting that `n` bytes have been filled.
263 ///
264 /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be
265 /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements
266 /// and its unfilled portion (and the capacity of this cursor) shrinks by `n` elements.
267 ///
268 /// If less than `n` bytes initialized (by the cursor's point of view), `set_init` should be
269 /// called first.
270 ///
271 /// # Panics
272 ///
273 /// Panics if there are less than `n` bytes initialized.
274 #[inline]
275 pub fn advance(&mut self, n: usize) -> &mut Self {
276 // The subtraction cannot underflow by invariant of this type.
277 assert!(n <= self.buf.init - self.buf.filled);
278
279 self.buf.filled += n;
280 self
281 }
282
283 /// Advances the cursor by asserting that `n` bytes have been filled.
284 ///
285 /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be
286 /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements
287 /// and its unfilled portion (and the capacity of this cursor) shrinks by `n` elements.
288 ///
289 /// # Safety
290 ///
291 /// The caller must ensure that the first `n` bytes of the cursor have been properly
292 /// initialised.
293 #[inline]
294 pub unsafe fn advance_unchecked(&mut self, n: usize) -> &mut Self {
295 self.buf.filled += n;
296 self.buf.init = cmp::max(self.buf.init, self.buf.filled);
297 self
298 }
299
300 /// Initializes all bytes in the cursor.
301 #[inline]
302 pub fn ensure_init(&mut self) -> &mut Self {
303 // SAFETY: always in bounds and we never uninitialize these bytes.
304 let uninit = unsafe { self.buf.buf.get_unchecked_mut(self.buf.init..) };
305
306 // SAFETY: 0 is a valid value for MaybeUninit<u8> and the length matches the allocation
307 // since it is comes from a slice reference.
308 unsafe {
309 ptr::write_bytes(uninit.as_mut_ptr(), 0, uninit.len());
310 }
311 self.buf.init = self.buf.capacity();
312
313 self
314 }
315
316 /// Asserts that the first `n` unfilled bytes of the cursor are initialized.
317 ///
318 /// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when
319 /// called with fewer bytes than are already known to be initialized.
320 ///
321 /// # Safety
322 ///
323 /// The caller must ensure that the first `n` bytes of the buffer have already been initialized.
324 #[inline]
325 pub unsafe fn set_init(&mut self, n: usize) -> &mut Self {
326 self.buf.init = cmp::max(self.buf.init, self.buf.filled + n);
327 self
328 }
329
330 /// Appends data to the cursor, advancing position within its buffer.
331 ///
332 /// # Panics
333 ///
334 /// Panics if `self.capacity()` is less than `buf.len()`.
335 #[inline]
336 pub fn append(&mut self, buf: &[u8]) {
337 assert!(self.capacity() >= buf.len());
338
339 // SAFETY: we do not de-initialize any of the elements of the slice
340 unsafe {
341 self.as_mut()[..buf.len()].write_copy_of_slice(buf);
342 }
343
344 // SAFETY: We just added the entire contents of buf to the filled section.
345 unsafe {
346 self.set_init(buf.len());
347 }
348 self.buf.filled += buf.len();
349 }
350
351 /// Runs the given closure with a `BorrowedBuf` containing the unfilled part
352 /// of the cursor.
353 ///
354 /// This enables inspecting what was written to the cursor.
355 ///
356 /// # Panics
357 ///
358 /// Panics if the `BorrowedBuf` given to the closure is replaced by another
359 /// one.
360 pub fn with_unfilled_buf<T>(&mut self, f: impl FnOnce(&mut BorrowedBuf<'_>) -> T) -> T {
361 let mut buf = BorrowedBuf::from(self.reborrow());
362 let prev_ptr = buf.buf as *const _;
363 let res = f(&mut buf);
364
365 // Check that the caller didn't replace the `BorrowedBuf`.
366 // This is necessary for the safety of the code below: if the check wasn't
367 // there, one could mark some bytes as initialized even though there aren't.
368 assert!(core::ptr::addr_eq(prev_ptr, buf.buf));
369
370 let filled = buf.filled;
371 let init = buf.init;
372
373 // Update `init` and `filled` fields with what was written to the buffer.
374 // `self.buf.filled` was the starting length of the `BorrowedBuf`.
375 //
376 // SAFETY: These amounts of bytes were initialized/filled in the `BorrowedBuf`,
377 // and therefore they are initialized/filled in the cursor too, because the
378 // buffer wasn't replaced.
379 self.buf.init = self.buf.filled + init;
380 self.buf.filled += filled;
381
382 res
383 }
384}
385