Tracking Issue for `core_io_borrowed_buf`

[jmillikin]

View all comments

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

See also: #78485

Unresolved Questions

• Now that it's generic (Make BorrowedBuf and BorrowedCursor generic over the data #149749) double-check any bounds we might want before stabilization
  • For example, it used to always be Debug (which was easy since u8: Debug), but for generic do we want always-Debug or only for T: Debug?

Naming:

• BorrowedCursor::written needs renaming to buf_written (implementation work only) Tracking Issue for core_io_borrowed_buf #117693 (comment)
• core::io or core::mem? Tracking Issue for core_io_borrowed_buf #117693 (comment), #t-libs > `io::BorrowedBuf` or `mem::BorrowedBuf`
• Should BorrowedCursor be renamed to BorrowedWriter? It's more similar to BufWriter than Cursor Tracking Issue for core_io_borrowed_buf #117693 (comment), #t-libs > Why is it called `io::BorrowedCursor`?
• General name confusion, specifically read_buf Tracking Issue for core_io_borrowed_buf #117693 (comment) (Concern 5)

Documentation:

• All API is missing examples, some is missing tests (implementation work only) Tracking Issue for core_io_borrowed_buf #117693 (comment) / Tracking Issue for core_io_borrowed_buf #117693 (comment)
• General documentation issues: needs to clarify why these two types exist rather than being combined Tracking Issue for core_io_borrowed_buf #117693 (comment), what exists is confusing and methods are not in useful order Tracking Issue for core_io_borrowed_buf #117693 (comment) (concern 1)

API confusion:

• BorrowedCursor::capacity indicates remaining capacity rather than total capacity, unlike Vec Tracking Issue for core_io_borrowed_buf #117693 (comment)
• Feature split with borrowed_buf_init is confusing: advance and advance_checked are split, affects as_mut Tracking Issue for core_io_borrowed_buf #117693 (comment), Tracking Issue for core_io_borrowed_buf #117693 (comment) (concern 3)
• Do we need both into_filled and into_filled_mut? Tracking Issue for core_io_borrowed_buf #117693 (comment)
• Should we add inherent constructors to avoid inference issues? (Not blocking) Tracking Issue for core_io_borrowed_buf #117693 (comment)
• Should we have is_empty? (Not blocking) Tracking Issue for core_io_borrowed_buf #117693 (comment)
• Unnecessary return of self Tracking Issue for core_io_borrowed_buf #117693 (comment)

Variance:

• We have BorrowedCursor<'data>, which would be invariant, but make it covariant with a lot of unsafe. This is fragile compared to BorrowedCursor<'buf, 'data> Tracking Issue for core_io_borrowed_buf #117693 (comment), Tracking Issue for core_io_borrowed_buf #117693 (comment), #t-libs > Why is it called `io::BorrowedCursor`? @ 💬

Trait and bounds:

• Should we print the filled portion during Debug? We don't have T: Debug in the current impl Tracking Issue for core_io_borrowed_buf #117693 (comment)
• Needless gates on T: Copy Tracking Issue for core_io_borrowed_buf #117693 (comment)

Other:

• This API has been contentious: confirm it is what we want over something like #t-libs > `buffer-trait` would overlap with `BorrowedBuf`

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.