Tracking Issue for `file_buffered`

[cuviper]

Feature gate: #![feature(file_buffered)]

This is a tracking issue for File constructors that return files wrapped with a buffer.

In addition to the light convenience, these are intended to raise visibility that buffering is something you should consider when opening a file, since unbuffered I/O is a common performance footgun to Rust newcomers.

Public API

// std::fs

impl File {
    pub fn open_buffered<P: AsRef<Path>>(path: P) -> io::Result<io::BufReader<File>>;
    pub fn create_buffered<P: AsRef<Path>>(path: P) -> io::Result<io::BufWriter<File>>;
}

Steps / History

• API Change Proposal (ACP): Add File constructors that nudge people toward buffered I/O libs-team#446
• Implementation: Add File constructors that return files wrapped with a buffer #130803
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Footnotes

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

[GeeWee]

Hey! I'm unsure whether I should create this as a new issue, or a comment on this feature, as it's quite related in scope.

In the scope of these changes, did we consider also changing fs::write to a buffered write? As far as I can tell it does non-buffered writes, and if we want to nudge people towards using buffered writes/reads by default, it seems odd to have a convenience method that does the "wrong thing".

I'm unsure however, if this would break the existing contract of fs::write - I'm not 100% sure if buffering the writes would end up giving different guarantees in practice.

[ginnyTheCat]

As far as I can tell it does non-buffered writes, and if we want to nudge people towards using buffered writes/reads by default, it seems odd to have a convenience method that does the "wrong thing".

In the best case fs::write only has to do a single write syscall.

If fs::write were to buffer the File before calling write_all on it, it would, if the contents fit in the buffer, write those to the buffer. In case they don't fit just call write_all . After that fs::write would need to flush (or drop, but that would lose the error) the buffer, which would call write_all if the buffer contains data. So this would end up doing the exact same syscalls as unbuffered, just with an extra allocation and more code involved.