Struct tokio_file::File

pub struct File { /* fields omitted */ }

Basically a Tokio file handle. This is the starting point for tokio-file.

Implementations

impl File

pub fn len(&self) -> Result<u64>

Get the file’s size in bytes

pub fn metadata(&self) -> Result<Metadata>

Get metadata from the underlying file

POSIX AIO doesn’t provide a way to do this asynchronously, so it must be synchronous.

pub fn new(file: File) -> File

Create a new Tokio File from an ordinary std::fs::File object

Examples

use std::fs;
use tokio_file;

fs::OpenOptions::new()
    .read(true)
    .write(true)
    .create(true)
    .open("/tmp/tokio-file-new-example")
    .map(tokio_file::File::new)
    .unwrap();

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

Open a new Tokio file with mode O_RDWR | O_CREAT.

pub fn read_at<'a>(&self, buf: &'a mut [u8], offset: u64) -> Result<AioFut<'a>>

Asynchronous equivalent of std::fs::File::read_at

Examples

use std::fs;
use std::io::Write;
use tempfile::TempDir;
use tokio::runtime::Runtime;

const WBUF: &[u8] = b"abcdef";
const EXPECT: &[u8] = b"cdef";
let mut rbuf = vec![0; 4];
let dir = TempDir::new().unwrap();
let path = dir.path().join("foo");
let mut f = fs::File::create(&path).unwrap();
f.write(WBUF).unwrap();

let file = fs::OpenOptions::new()
    .read(true)
    .open(&path)
    .map(tokio_file::File::new)
    .unwrap();
let mut rt = Runtime::new().unwrap();
let r = rt.block_on(async {
    file.read_at(&mut rbuf[..], 2).unwrap().await
}).unwrap();
assert_eq!(&rbuf[..], &EXPECT[..]);

pub fn readv_at<'a>(
    &self,
    bufs: &'a mut [&'a mut [u8]],
    offset: u64
) -> Result<ReadvAt<'a>>

Asynchronous equivalent of preadv.

Similar to preadv(2) but asynchronous. Reads a contiguous portion of a file into a scatter-gather list of buffers. Unlike preadv, there is no guarantee of overall atomicity. Each scatter gather element’s contents could reflect the state of the file at a different point in time.

Parameters

• bufs: The destination for the read. A scatter-gather list of buffers.
• offset: Offset within the file at which to begin the read

Returns

• Ok(x): The operation was successfully created. The future may be polled and will eventually return the final status of the operation. If the operation was partially successful, the future will complete an error with no indication of which parts of bufs are valid.
• Err(x): An error occurred before issueing the operation. The result may be dropped.

Examples

use std::borrow::BorrowMut;
use std::fs;
use std::io::Write;
use tempfile::TempDir;
use tokio::runtime::Runtime;

const WBUF: &[u8] = b"abcdefghijklmnopqrwtuvwxyz";
const EXPECT0: &[u8] = b"cdef";
const EXPECT1: &[u8] = b"ghijklmn";
let l0 = 4;
let l1 = 8;
let mut rbuf0 = vec![0; l0];
let mut rbuf1 = vec![0; l1];
let mut rbufs = [&mut rbuf0[..], &mut rbuf1[..]];

let dir = TempDir::new().unwrap();
let path = dir.path().join("foo");
let mut f = fs::File::create(&path).unwrap();
f.write(WBUF).unwrap();

let file = fs::OpenOptions::new()
    .read(true)
    .open(&path)
    .map(tokio_file::File::new)
    .unwrap();
let mut rt = Runtime::new().unwrap();
let mut r = rt.block_on(async {
    file.readv_at(&mut rbufs[..], 2).unwrap().await
}).unwrap();

assert_eq!(l0 + l1, r);
assert_eq!(&rbuf0[..], &EXPECT0[..]);
assert_eq!(&rbuf1[..], &EXPECT1[..]);

pub fn write_at<'a>(&self, buf: &'a [u8], offset: u64) -> Result<AioFut<'a>>

Asynchronous equivalent of std::fs::File::write_at.

Examples

use std::fs;
use std::io::Read;
use tempfile::TempDir;
use tokio::runtime::Runtime;

let contents = b"abcdef";
let mut rbuf = Vec::new();

let dir = TempDir::new().unwrap();
let path = dir.path().join("foo");
let file = fs::OpenOptions::new()
    .create(true)
    .write(true)
    .open(&path)
    .map(tokio_file::File::new)
    .unwrap();
let mut rt = Runtime::new().unwrap();
let r = rt.block_on(async {
    file.write_at(contents, 0).unwrap().await
}).unwrap();
assert_eq!(r.value.unwrap() as usize, contents.len());
drop(file);

let mut file = fs::File::open(&path).unwrap();
assert_eq!(file.read_to_end(&mut rbuf).unwrap(), contents.len());
assert_eq!(&contents[..], &rbuf[..]);

pub fn writev_at<'a>(
    &self,
    bufs: &[&'a [u8]],
    offset: u64
) -> Result<WritevAt<'a>>

Asynchronous equivalent of pwritev

Similar to pwritev(2) but asynchronous. Writes a scatter-gather list of buffers into a contiguous portion of a file. Unlike pwritev, there is no guarantee of overall atomicity. Each scatter gather element’s contents are written independently.

Parameters

• bufs: The data to write. A scatter-gather list of buffers.
• offset: Offset within the file at which to begin the write

Returns

• Ok(x): The operation was successfully created. The future may be polled and will eventually return the final status of the operation. If the operation was partially successful, the future will complete an error with no indication of which parts of the file were actually written.
• Err(x): An error occurred before issueing the operation. The result may be dropped.

Examples

use std::fs;
use std::io::Read;
use tempfile::TempDir;
use tokio::runtime::Runtime;

const EXPECT: &[u8] = b"abcdefghij";
let wbuf0 = b"abcdef";
let wbuf1 = b"ghij";
let wbufs = vec![&wbuf0[..], &wbuf1[..]];
let mut rbuf = Vec::new();

let dir = TempDir::new().unwrap();
let path = dir.path().join("foo");
let file = fs::OpenOptions::new()
    .create(true)
    .write(true)
    .open(&path)
    .map(tokio_file::File::new)
    .unwrap();
let mut rt = Runtime::new().unwrap();
let r = rt.block_on(async {
    file.writev_at(&wbufs[..], 0).unwrap().await
}).unwrap();

assert_eq!(r, 10);

let mut f = fs::File::open(&path).unwrap();
let len = f.read_to_end(&mut rbuf).unwrap();
assert_eq!(len, EXPECT.len());
assert_eq!(rbuf, EXPECT);

pub fn sync_all(&self) -> Result<AioFut<'static>>

Asynchronous equivalent of std::fs::File::sync_all

Examples

use std::borrow::BorrowMut;
use std::fs;
use std::io::Write;
use tempfile::TempDir;
use tokio::runtime::Runtime;

let dir = TempDir::new().unwrap();
let path = dir.path().join("foo");

let file = fs::OpenOptions::new()
    .write(true)
    .create(true)
    .open(&path)
    .map(tokio_file::File::new)
    .unwrap();
let mut rt = Runtime::new().unwrap();
let r = rt.block_on(async {
    file.sync_all().unwrap().await
}).unwrap();

Trait Implementations

impl AsRawFd for File

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for File

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.