Struct tokio_file::File

pub struct File { /* private fields */ }

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<ReadAt<'a>>

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

Examples

use std::fs;
use std::io::Write;
use tempfile::TempDir;
use tokio::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 rt = runtime::Builder::new_current_thread()
    .enable_io()
    .build()
    .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 [IoSliceMut<'a>], 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.

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.
• 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::{IoSliceMut, Write};
use tempfile::TempDir;
use tokio::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 = [IoSliceMut::new(&mut rbuf0), IoSliceMut::new(&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 rt = runtime::Builder::new_current_thread()
    .enable_io()
    .build()
    .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 sync_all(&self) -> Result<SyncAll>

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;

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 rt = runtime::Builder::new_current_thread()
    .enable_io()
    .build()
    .unwrap();
let r = rt.block_on(async {
    file.sync_all().unwrap().await
}).unwrap();

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

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

Examples

use std::fs;
use std::io::Read;
use tempfile::TempDir;
use tokio::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 rt = runtime::Builder::new_current_thread()
    .enable_io()
    .build()
    .unwrap();
let r = rt.block_on(async {
    file.write_at(contents, 0).unwrap().await
}).unwrap();
assert_eq!(r, 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: &[IoSlice<'a>], 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.

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

Examples

use std::fs;
use std::io::{IoSlice, Read};
use tempfile::TempDir;
use tokio::runtime;

const EXPECT: &[u8] = b"abcdefghij";
let wbuf0 = b"abcdef";
let wbuf1 = b"ghij";
let wbufs = vec![IoSlice::new(wbuf0), IoSlice::new(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 rt = runtime::Builder::new_current_thread()
    .enable_io()
    .build()
    .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);

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.