Struct cros_asyncv2::File

source · [−]

pub struct File {
    inner: File,
}

Expand description

A reference to an open file on the filesystem.

File provides asynchronous functions for reading and writing data. When a File is dropped, the underlying OS handle will be closed once there are no more pending I/O operations on it.

Errors

Many File methods return an anyhow::Result. However, it is guaranteed that if an error is returned, that error is downcastable to an io::Error.

Examples

Create a new file and write data to it.

    let mut f = File::create(path)?;
    f.write_all(b"Hello, world!", None).await

Extract an io::Error from a failed operation.

    if let Err(e) = File::open("nonexistent-filesystem-path") {
        e.downcast::<io::Error>().expect("Error not downcastable to `io::Error`")
    } else {
        panic!("nonexistent path exists");
    }

Fields

inner: File

Implementations

source

impl File

source

pub fn open<P: AsRef<Path>>(p: P) -> Result<File>

Attempt to open a file in read-only mode.

This is a convenience wrapper for the standard library File::open method.

source

pub fn create<P: AsRef<Path>>(p: P) -> Result<File>

Attempt to open a file in write-only mode.

This function will create a file if it does not exist, and will truncate it if it does. It is a convenience wrapper for the File::create method from the standard library.

source

pub fn from_std(f: StdFile) -> Result<File>

Create a File from a standard library file.

The conversion may fail if the underlying OS handle cannot be prepared for asynchronous operation. For example on epoll-based systems, this requires making the handle non-blocking.

source

pub fn into_std(self) -> Result<StdFile, File>

Convert a File back into a standard library file.

The conversion may fail if there are still pending asynchronous operations on the underlying OS handle. In this case, the original File is returned as the error.

source

pub async fn read(&self, buf: &mut [u8], offset: Option<u64>) -> Result<usize>

Read up to buf.len() bytes from the file starting at offset into buf, returning the number of bytes read.

If offset is None then the bytes are read starting from the kernel offset for the underlying OS file handle. Callers should take care when calling this method from multiple threads without providing offset as the order in which the operations will execute is undefined.

When using I/O drivers like io_uring, data may be copied from an internal buffer into buf so this function is best suited for reading small amounts of data. Callers that wish to avoid copying data may want to use File::read_iobuf instead. Additionally, dropping this async fn after it has started may not cancel the underlying asynchronous operation.

source

pub async fn read_exact(&self, buf: &mut [u8], offset: Option<u64>) -> Result<()>

Read exactly buf.len() bytes from the file starting at offset into buf.

This method calls File::read in a loop until buf.len() bytes have been read from the underlying file. Callers should take care when calling this method from multiple threads without providing offset as the order in which data is read is undefined and the data returned in buf may not be from contiguous regions in the underlying file.

When using I/O drivers like io_uring, data may be copied from an internal buffer into buf. Callers that wish to avoid copying data may want to use File::read_iobuf instead. Additionally, dropping this async fn after it has started may not cancel the underlying asynchronous operation.

Errors

This function will directly return any non-io::ErrorKind::Interrupted errors. In this case, the number of bytes read from the underlying file and the kernel offset are undefined.

source

pub async fn read_iobuf<B: AsIoBufs + Unpin + 'static>(
 &self,
 buf: B,
 offset: Option<u64>
) -> (Result<usize>, B)

Reads data from the underlying data starting at offset into an owned buffer.

This method is like File::read but takes ownership of the buffer. When using I/O drivers like io_uring, this can improve performance by avoiding the need to first read the data into an internal buffer. Dropping this async fn may not cancel the underlying I/O operation.

Examples

Read file data into a Vec<u8>.

    use cros_async::{File, OwnedIoBuf};

    let f = File::open("/dev/zero")?;
    let buf = OwnedIoBuf::new(vec![0xcc; 64]);

    let (res, buf) = f.read_iobuf(buf, None).await;
    let count = res?;

    let orig: Vec<u8> = buf.into_inner();
    assert!(count <= 64);
    assert_eq!(&orig[..count], &[0u8; 64][..count]);

source

pub async fn write(&self, buf: &[u8], offset: Option<u64>) -> Result<usize>

Write up to buf.len() bytes from buf to the file starting at offset, returning the number of bytes written.

If offset is None then the bytes are written starting from the kernel offset for the underlying OS file handle. Callers should take care when calling this method from multiple threads without providing offset as the order in which the operations will execute is undefined.

When using I/O drivers like io_uring, data may be copied into an internal buffer from buf so this function is best suited for writing small amounts of data. Callers that wish to avoid copying data may want to use File::write_iobuf instead. Additionally, dropping this async fn after it has started may not cancel the underlying asynchronous operation.

source

pub async fn write_all(&self, buf: &[u8], offset: Option<u64>) -> Result<()>

Write all the data from buf into the underlying file starting at offset.

This method calls File::write in a loop until buf.len() bytes have been written to the underlying file. Callers should take care when calling this method from multiple threads without providing offset as the order in which data is written is undefined and the data written to the file may not be contiguous with respect to buf.

When using I/O drivers like io_uring, data may be copied into an internal buffer from buf. Callers that wish to avoid copying data may want to use File::write_iobuf instead. Additionally, dropping this async fn after it has started may not cancel the underlying asynchronous operation.

Errors

This function will directly return any non-io::ErrorKind::Interrupted errors. In this case, the number of bytes written to the underlying file and the kernel offset are undefined.

source

pub async fn write_iobuf<B: AsIoBufs + Unpin + 'static>(
 &self,
 buf: B,
 offset: Option<u64>
) -> (Result<usize>, B)

Writes data from an owned buffer into the underlying file at offset.

This method is like File::write but takes ownership of the buffer. When using I/O drivers like io_uring, this can improve performance by avoiding the need to first copy the data into an internal buffer. Dropping this async fn may not cancel the underlying I/O operation.

Examples

Write file data from a Vec<u8>.

    use cros_async::{File, OwnedIoBuf};

    let f = File::open("/dev/null")?;
    let buf = OwnedIoBuf::new(vec![0xcc; 64]);

    let (res, buf) = f.write_iobuf(buf, None).await;
    let count = res?;

    let orig: Vec<u8> = buf.into_inner();
    assert!(count <= 64);