Tracking Issue for core_io_borrowed_buf

[jmillikin]

Feature gate: #![feature(core_io_borrowed_buf)]

This is a tracking issue for an MVP of core::io, which contains an OS-independent subset of std::io.

Public API

The initial API of this module consists of BorrowedBuf and BorrowedCursor, which were previously only available in std.

Steps / History

• std::io: migrate ReadBuf to BorrowedBuf/BorrowedCursor #97015
• Move BorrowedBuf and BorrowedCursor from std:io to core::io #117694
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[tgross35]

These types in core could use a core::fmt::Write impl, but I am not sure how this is possible without conflicting with the blanket impl for std::io::Write.

[taralx]

Is the intent to stabilize this at the same time as #78485 or independently of it?

[kornelski]

I'm surprised that this doesn't have any safe integration with Vec. I'd like to have vec.as_borrowed_buf() that can safely append to the uninitialized capacity, without having to manually perform unsafe vec.set_len correction afterwards.

[keepsimple1]

If I understand, BorrowedBuf (like MaybeUninit) essentially is safe to write, may I suggest adding a method to the API of BorrowedBuf:

/// Copies the bytes of `buf` to self starting at `offset`.
///  Returns the number of bytes actually written.
///
/// If `offset` is equal or larger than `self.buf.len()`, returns 0.
/// If `offset` is larger than `self.init`, the region `self.buf[self.init..offset]` is zeroed. 
pub fn write(&mut self, offset: usize, buf: &[u8]) -> usize

(this method updates filled and init accordingly)

The idea is to make the API even easier to use:

• Simpler: no need to use BorrowedCursor for such use cases.
• No need to use different APIs to write filled / init section and uninit sections.
• No panics (from this method) as it returns the written length.
• Compatible with existing API.

What do you think?

[hxuhack]

According to the source code, Capacity() returns self.filled, which appears inconsistent with the descriptions of capacity, filled, and initialized.

[yoshuawuyts]

.@sunfishcode wrote about an alternative to the BorrowedBuf APIs in Writing into uninitialized buffers in Rust. The design outlined there is based on the APIs used in bytecodealliance/rustix, and is based on a new trait Buffer that can abstract over both e.g. Vec<T> and &mut [MaybeUninit<T>].

While this tracking issue is not the right avenue to discuss the tradeoffs and differences between the two APIs ¹, I wanted to make sure that it was mentioned on this tracking issue. It seems like a credible alternative to the BorrowedBuf API, and I believe it's worth considering going forward. Or at the very least: the blog post is well worth a read.

Footnotes

1. Zulip would be a better avenue for that. I don't believe there is a thread yet, but anyone is free to start one if they want to. ↩

[briansmith]

1. Zulip would be a better avenue for that. I don't believe there is a thread yet, but anyone is free to start one if they want to. ↩

There are three threads, two of them are old:

• BorrowedBuf/BorrowedCursor optimized for past, not future
• BorrowedBuf/BorrowedCursor would benefit by being generic
• BorrowedCursor::buf lifetimes from BorrowedBuf::unfilled