Add back `BorrowedBuf::filled_mut`

[SUPERCILEX]

Proposal

Problem statement

The current BorrowedBuf API has no way to modify the filled data without using unsafe. This blocks several use cases:

• Preprocessing data before giving someone else the filled buf.
• Taking in an uninitialized buffer and returning an initialized buffer with the same lifetime that allows mutation.
• Any kind of in place mutation using the initialized data.

Motivation, use-cases

Need to mutate the initialized buffer for various reasons.

Solution sketches

See rust-lang/rust#103754. TL;DR: add

fn filled_mut(&mut self) -> &mut [u8]

Links and related work

filled_mut was part of the original RFC, but was removed during the split into BorrowedBuf and BorrowedCursor. The cited rationale is to make BorrowedBuf read-only and BorrowedCursor write-only. I don't believe this logic holds up for a number of reasons:

• The original uninitialized buffer that's passed in is mutable, therefore that buffer's owner cannot make any guarantees about their buffer, regardless of the presence of filled_mut.
• The BorrowedBuf has access to the mutable buffer which means you can always mess around with filled part by finagling around with clear, unfilled, and set_init. Again, this means adding filled_mut does not weaken the guarantees made by BorrowedBuf in any way.
• Without mutable access to the filled buffer, the read-buf family of APIs becomes limited to read-only views of loaded data when using only safe Rust. But the purpose of this API is to avoid the need for unsafe.
  • The alternative is to drop the BorrowedBuf (which can be annoying for a number of reasons) and manually convert the underlying MaybeUninit buffer to initialized u8s using unsafe.

[m-ou-se]

We briefly discussed this in today's meeting. Adding filled_mut back is fine. :)

[SUPERCILEX]

Thank you so much! 🙏