Tracking Issue for `core_io_borrowed_buf`

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

• https://github.com/rust-lang/rust/pull/97015
• https://github.com/rust-lang/rust/pull/117694
• Final comment period (FCP)^1
• Stabilization PR

See also: https://github.com/rust-lang/rust/issues/78485

Unresolved Questions

• Now that it's generic (#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) https://github.com/rust-lang/rust/issues/117693#issuecomment-5106705125
• core::io or core::mem? https://github.com/rust-lang/rust/issues/117693#issuecomment-5156999054, #t-libs > `io::BorrowedBuf` or `mem::BorrowedBuf`
• Should BorrowedCursor be renamed to BorrowedWriter? It's more similar to BufWriter than Cursor https://github.com/rust-lang/rust/issues/117693#issuecomment-5182654686, #t-libs > Why is it called `io::BorrowedCursor`?
• General name confusion, specifically read_buf https://github.com/rust-lang/rust/issues/117693#issuecomment-5207802573 (Concern 5)

Documentation:

• All API is missing examples, some is missing tests (implementation work only) https://github.com/rust-lang/rust/issues/117693#issuecomment-5109936825 / https://github.com/rust-lang/rust/issues/117693#issuecomment-5160382935
• General documentation issues: needs to clarify why these two types exist rather than being combined https://github.com/rust-lang/rust/issues/117693#issuecomment-5182654686, what exists is confusing and methods are not in useful order https://github.com/rust-lang/rust/issues/117693#issuecomment-5207802573 (concern 1)

API confusion:

• BorrowedCursor::capacity indicates remaining capacity rather than total capacity, unlike Vec https://github.com/rust-lang/rust/issues/117693#issuecomment-5170391734
• Feature split with borrowed_buf_init is confusing: advance and advance_checked are split, affects as_mut https://github.com/rust-lang/rust/issues/117693#issuecomment-5173597407, https://github.com/rust-lang/rust/issues/117693#issuecomment-5207802573 (concern 3)
• Do we need both into_filled and into_filled_mut? https://github.com/rust-lang/rust/issues/117693#issuecomment-5173650638
• Should we add inherent constructors to avoid inference issues? (Not blocking) https://github.com/rust-lang/rust/issues/117693#issuecomment-5183461507
• Should we have is_empty? (Not blocking) https://github.com/rust-lang/rust/issues/117693#issuecomment-5260411124
• Unnecessary return of self https://github.com/rust-lang/rust/issues/117693#issuecomment-5207802573
• written confusion, position as an alternative https://github.com/rust-lang/rust/issues/117693#issuecomment-5359723201

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> https://github.com/rust-lang/rust/issues/117693#issuecomment-5180050759, https://github.com/rust-lang/rust/issues/117693#issuecomment-5208964609, #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 https://github.com/rust-lang/rust/issues/117693#issuecomment-5173759271
• Needless gates on T: Copy https://github.com/rust-lang/rust/issues/117693#issuecomment-5207802573

Other:

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

Start with the core::io feature gate and the public APIs BorrowedBuf and BorrowedCursor, then read the unresolved questions and linked discussion. The tracking issue lists naming, documentation, API, variance, and trait concerns that require resolution before stabilization. Done means the remaining decisions are resolved and a stabilization PR is prepared.