Struct tokio_file::File

pub struct File { /* fields omitted */ }

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

Methods

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(
    &self,
    buf: Box<dyn BorrowMut<[u8]>>,
    offset: u64
) -> Result<AioFut>

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

Note that it consumes buf rather than references it. When the operation is complete, the buffer can be retrieved with AioResult::into_buf_ref.

Examples

use std::borrow::BorrowMut;
use std::fs;
use std::io::Write;
use tempdir::TempDir;
use tokio::runtime::current_thread;

const WBUF: &[u8] = b"abcdef";
const EXPECT: &[u8] = b"cdef";
let rbuf = Box::new(vec![0; 4].into_boxed_slice());
let dir = TempDir::new("tokio-file").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 = current_thread::Runtime::new().unwrap();
let r = rt.block_on(
    file.read_at(rbuf, 2).unwrap()
).unwrap();

let mut buf_ref = r.into_buf_ref();
let borrowed : &mut BorrowMut<[u8]> = buf_ref.boxed_mut_slice()
                                             .unwrap();
assert_eq!(&borrowed.borrow_mut()[..], &EXPECT[..]);

pub fn readv_at(
    &self,
    bufs: Vec<Box<dyn BorrowMut<[u8]>>>,
    offset: u64
) -> Result<LioFut>

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 tempdir::TempDir;
use tokio::runtime::current_thread;

const WBUF: &[u8] = b"abcdefghijklmnopqrwtuvwxyz";
const EXPECT0: &[u8] = b"cdef";
const EXPECT1: &[u8] = b"ghijklmn";
let rbuf0 = Box::new(vec![0; 4].into_boxed_slice());
let rbuf1 = Box::new(vec![0; 8].into_boxed_slice());
let rbufs : Vec<Box<dyn BorrowMut<[u8]>>> = vec![rbuf0, rbuf1];

let dir = TempDir::new("tokio-file").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 = current_thread::Runtime::new().unwrap();
let mut ri = rt.block_on(
    file.readv_at(rbufs, 2).unwrap()
).unwrap();

let mut r0 = ri.next().unwrap();
let b0 : &mut BorrowMut<[u8]> =
    r0.buf.boxed_mut_slice().unwrap();
assert_eq!(&b0.borrow_mut()[..], &EXPECT0[..]);

let mut r1 = ri.next().unwrap();
let b1 : &mut BorrowMut<[u8]> =
    r1.buf.boxed_mut_slice().unwrap();
assert_eq!(&b1.borrow_mut()[..], &EXPECT1[..]);

assert!(ri.next().is_none());

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

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

Note that it consumes buf rather than references it. When the operation is complete, the buffer can be retrieved with AioResult::into_buf_ref.

Examples

use std::borrow::Borrow;
use std::fs;
use std::io::Read;
use tempdir::TempDir;
use tokio::runtime::current_thread;

let contents = b"abcdef";
let wbuf: Box<dyn Borrow<[u8]>> = Box::new(&contents[..]);
let mut rbuf = Vec::new();

let dir = TempDir::new("tokio-file").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 = current_thread::Runtime::new().unwrap();
let r = rt.block_on(
    file.write_at(wbuf, 0).unwrap()
).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(
    &self,
    bufs: Vec<Box<dyn Borrow<[u8]>>>,
    offset: u64
) -> Result<LioFut>

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 bufs are valid.
• Err(x): An error occurred before issueing the operation. The result may be dropped.

Examples

use std::borrow::Borrow;
use std::fs;
use std::io::Read;
use tempdir::TempDir;
use tokio::runtime::current_thread;

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

let dir = TempDir::new("tokio-file").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 = current_thread::Runtime::new().unwrap();
let mut wi = rt.block_on(
    file.writev_at(wbufs, 0).unwrap()
).unwrap();

let w0 = wi.next().unwrap();
assert_eq!(w0.value.unwrap() as usize, 6);
let w1 = wi.next().unwrap();
assert_eq!(w1.value.unwrap() as usize, 4);

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>

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

Examples

use std::borrow::BorrowMut;
use std::fs;
use std::io::Write;
use tempdir::TempDir;
use tokio::runtime::current_thread;

let dir = TempDir::new("tokio-file").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 = current_thread::Runtime::new().unwrap();
let r = rt.block_on(
    file.sync_all().unwrap()
).unwrap();

Trait Implementations

impl Debug for File

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

Formats the value using the given formatter.

impl AsRawFd for File

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.