Skip to content

Commit 4a7aeff

Browse files
borsbors
committed
Auto merge of rust-lang#130803 - cuviper:file-buffered, r=joshtriplett
Add `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. ACP: rust-lang/libs-team#446 Tracking Issue: rust-lang#130804
2 parents 2c408b1 + 2ab86f0 commit 4a7aeff

File tree

8 files changed

+112
-7
lines changed

8 files changed

+112
-7
lines changed

‎std/src/fs.rs

+77
Original file line numberDiff line numberDiff line change
@@ -375,6 +375,44 @@ impl File {
375375
OpenOptions::new().read(true).open(path.as_ref())
376376
}
377377

378+
/// Attempts to open a file in read-only mode with buffering.
379+
///
380+
/// See the [`OpenOptions::open`] method, the [`BufReader`][io::BufReader] type,
381+
/// and the [`BufRead`][io::BufRead] trait for more details.
382+
///
383+
/// If you only need to read the entire file contents,
384+
/// consider [`std::fs::read()`][self::read] or
385+
/// [`std::fs::read_to_string()`][self::read_to_string] instead.
386+
///
387+
/// # Errors
388+
///
389+
/// This function will return an error if `path` does not already exist.
390+
/// Other errors may also be returned according to [`OpenOptions::open`].
391+
///
392+
/// # Examples
393+
///
394+
/// ```no_run
395+
/// #![feature(file_buffered)]
396+
/// use std::fs::File;
397+
/// use std::io::BufRead;
398+
///
399+
/// fn main() -> std::io::Result<()> {
400+
/// let mut f = File::open_buffered("foo.txt")?;
401+
/// assert!(f.capacity() > 0);
402+
/// for (line, i) in f.lines().zip(1..) {
403+
/// println!("{i:6}: {}", line?);
404+
/// }
405+
/// Ok(())
406+
/// }
407+
/// ```
408+
#[unstable(feature = "file_buffered", issue = "130804")]
409+
pub fn open_buffered<P: AsRef<Path>>(path: P) -> io::Result<io::BufReader<File>> {
410+
// Allocate the buffer *first* so we don't affect the filesystem otherwise.
411+
let buffer = io::BufReader::<Self>::try_new_buffer()?;
412+
let file = File::open(path)?;
413+
Ok(io::BufReader::with_buffer(file, buffer))
414+
}
415+
378416
/// Opens a file in write-only mode.
379417
///
380418
/// This function will create a file if it does not exist,
@@ -404,6 +442,45 @@ impl File {
404442
OpenOptions::new().write(true).create(true).truncate(true).open(path.as_ref())
405443
}
406444

445+
/// Opens a file in write-only mode with buffering.
446+
///
447+
/// This function will create a file if it does not exist,
448+
/// and will truncate it if it does.
449+
///
450+
/// Depending on the platform, this function may fail if the
451+
/// full directory path does not exist.
452+
///
453+
/// See the [`OpenOptions::open`] method and the
454+
/// [`BufWriter`][io::BufWriter] type for more details.
455+
///
456+
/// See also [`std::fs::write()`][self::write] for a simple function to
457+
/// create a file with some given data.
458+
///
459+
/// # Examples
460+
///
461+
/// ```no_run
462+
/// #![feature(file_buffered)]
463+
/// use std::fs::File;
464+
/// use std::io::Write;
465+
///
466+
/// fn main() -> std::io::Result<()> {
467+
/// let mut f = File::create_buffered("foo.txt")?;
468+
/// assert!(f.capacity() > 0);
469+
/// for i in 0..100 {
470+
/// writeln!(&mut f, "{i}")?;
471+
/// }
472+
/// f.flush()?;
473+
/// Ok(())
474+
/// }
475+
/// ```
476+
#[unstable(feature = "file_buffered", issue = "130804")]
477+
pub fn create_buffered<P: AsRef<Path>>(path: P) -> io::Result<io::BufWriter<File>> {
478+
// Allocate the buffer *first* so we don't affect the filesystem otherwise.
479+
let buffer = io::BufWriter::<Self>::try_new_buffer()?;
480+
let file = File::create(path)?;
481+
Ok(io::BufWriter::with_buffer(file, buffer))
482+
}
483+
407484
/// Creates a new file in read-write mode; error if the file exists.
408485
///
409486
/// This function will create a file if it does not exist, or return an error if it does. This

‎std/src/io/buffered/bufreader.rs

+8
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,14 @@ impl<R: Read> BufReader<R> {
7474
BufReader::with_capacity(DEFAULT_BUF_SIZE, inner)
7575
}
7676

77+
pub(crate) fn try_new_buffer() -> io::Result<Buffer> {
78+
Buffer::try_with_capacity(DEFAULT_BUF_SIZE)
79+
}
80+
81+
pub(crate) fn with_buffer(inner: R, buf: Buffer) -> Self {
82+
Self { inner, buf }
83+
}
84+
7785
/// Creates a new `BufReader<R>` with the specified buffer capacity.
7886
///
7987
/// # Examples

‎std/src/io/buffered/bufreader/buffer.rs

+11-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
//! without encountering any runtime bounds checks.
1111
1212
use crate::cmp;
13-
use crate::io::{self, BorrowedBuf, Read};
13+
use crate::io::{self, BorrowedBuf, ErrorKind, Read};
1414
use crate::mem::MaybeUninit;
1515

1616
pub struct Buffer {
@@ -36,6 +36,16 @@ impl Buffer {
3636
Self { buf, pos: 0, filled: 0, initialized: 0 }
3737
}
3838

39+
#[inline]
40+
pub fn try_with_capacity(capacity: usize) -> io::Result<Self> {
41+
match Box::try_new_uninit_slice(capacity) {
42+
Ok(buf) => Ok(Self { buf, pos: 0, filled: 0, initialized: 0 }),
43+
Err(_) => {
44+
Err(io::const_io_error!(ErrorKind::OutOfMemory, "failed to allocate read buffer"))
45+
}
46+
}
47+
}
48+
3949
#[inline]
4050
pub fn buffer(&self) -> &[u8] {
4151
// SAFETY: self.pos and self.cap are valid, and self.cap => self.pos, and

‎std/src/io/buffered/bufwriter.rs

+10
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,16 @@ impl<W: Write> BufWriter<W> {
9494
BufWriter::with_capacity(DEFAULT_BUF_SIZE, inner)
9595
}
9696

97+
pub(crate) fn try_new_buffer() -> io::Result<Vec<u8>> {
98+
Vec::try_with_capacity(DEFAULT_BUF_SIZE).map_err(|_| {
99+
io::const_io_error!(ErrorKind::OutOfMemory, "failed to allocate write buffer")
100+
})
101+
}
102+
103+
pub(crate) fn with_buffer(inner: W, buf: Vec<u8>) -> Self {
104+
Self { inner, buf, panicked: false }
105+
}
106+
97107
/// Creates a new `BufWriter<W>` with at least the specified buffer capacity.
98108
///
99109
/// # Examples

‎std/src/lib.rs

+1
Original file line numberDiff line numberDiff line change
@@ -374,6 +374,7 @@
374374
#![feature(slice_concat_trait)]
375375
#![feature(thin_box)]
376376
#![feature(try_reserve_kind)]
377+
#![feature(try_with_capacity)]
377378
#![feature(vec_into_raw_parts)]
378379
// tidy-alphabetical-end
379380
//

‎std/src/sys/pal/unix/thread.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -517,7 +517,7 @@ mod cgroups {
517517
use crate::borrow::Cow;
518518
use crate::ffi::OsString;
519519
use crate::fs::{File, exists};
520-
use crate::io::{BufRead, BufReader, Read};
520+
use crate::io::{BufRead, Read};
521521
use crate::os::unix::ffi::OsStringExt;
522522
use crate::path::{Path, PathBuf};
523523
use crate::str::from_utf8;
@@ -690,7 +690,7 @@ mod cgroups {
690690
/// If the cgroupfs is a bind mount then `group_path` is adjusted to skip
691691
/// over the already-included prefix
692692
fn find_mountpoint(group_path: &Path) -> Option<(Cow<'static, str>, &Path)> {
693-
let mut reader = BufReader::new(File::open("/proc/self/mountinfo").ok()?);
693+
let mut reader = File::open_buffered("/proc/self/mountinfo").ok()?;
694694
let mut line = String::with_capacity(256);
695695
loop {
696696
line.clear();

‎test/src/lib.rs

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
#![doc(test(attr(deny(warnings))))]
1919
#![doc(rust_logo)]
2020
#![feature(rustdoc_internals)]
21+
#![feature(file_buffered)]
2122
#![feature(internal_output_capture)]
2223
#![feature(staged_api)]
2324
#![feature(process_exitcode_internals)]

‎test/src/term/terminfo/mod.rs

+2-4
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@
33
use std::collections::HashMap;
44
use std::fs::File;
55
use std::io::prelude::*;
6-
use std::io::{self, BufReader};
76
use std::path::Path;
8-
use std::{env, error, fmt};
7+
use std::{env, error, fmt, io};
98

109
use parm::{Param, Variables, expand};
1110
use parser::compiled::{msys_terminfo, parse};
@@ -102,8 +101,7 @@ impl TermInfo {
102101
}
103102
// Keep the metadata small
104103
fn _from_path(path: &Path) -> Result<TermInfo, Error> {
105-
let file = File::open(path).map_err(Error::IoError)?;
106-
let mut reader = BufReader::new(file);
104+
let mut reader = File::open_buffered(path).map_err(Error::IoError)?;
107105
parse(&mut reader, false).map_err(Error::MalformedTerminfo)
108106
}
109107
}

0 commit comments

Comments
 (0)