Struct tokio_file_unix::File

pub struct File<F> { /* fields omitted */ }

Wraps file-like objects for asynchronous I/O.

Normally, you should use File::new_nb rather than File::raw_new unless the underlying file descriptor has already been set to nonblocking mode. Using a file descriptor that is not in nonblocking mode for asynchronous I/O will lead to subtle and confusing bugs.

Wrapping regular files has no effect because they do not support nonblocking mode.

The most common instantiation of this type is File<std::fs::File>, which indirectly provides the following trait implementation:

impl AsyncRead + AsyncWrite for PollEvented<File<std::fs::File>>;

Example: read standard input line by line

use tokio::stream::StreamExt;
use tokio_util::codec::FramedRead;
use tokio_util::codec::LinesCodec;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // convert stdin into a nonblocking file;
    // this is the only part that makes use of tokio_file_unix
    let file = tokio_file_unix::raw_stdin()?;
    let file = tokio_file_unix::File::new_nb(file)?;

    let mut framed = FramedRead::new(file, LinesCodec::new());

    while let Some(got) = framed.next().await {
        println!("Got this: {:?}", got);
    }

    println!("Received None, lol");
    Ok(())
}

Example: unsafe creation from raw file descriptor

To unsafely create File<F> from a raw file descriptor fd, you can do something like:

use std::os::unix::io::FromRawFd;

let file = tokio_file_unix::File::new_nb(F::from_raw_fd(fd))?;

which will enable nonblocking mode upon creation. The choice of F is critical: it determines the ownership semantics of the file descriptor. For example, if you choose F = std::fs::File, the file descriptor will be closed when the File is dropped.

Implementations

impl<F: AsRawFd> File<F>

pub fn new_nb(file: F) -> Result<PollEvented<Self>>

Wraps a file-like object into a pollable object that supports tokio::io::AsyncRead and tokio::io::AsyncWrite, and also enables nonblocking mode on the underlying file descriptor.

pub fn raw_new(file: F) -> Result<PollEvented<Self>>

Raw constructor that does not enable nonblocking mode on the underlying file descriptor. This constructor should only be used if you are certain that the underlying file descriptor is already in nonblocking mode.

Trait Implementations

impl<F: AsRawFd> AsRawFd for File<F>

pub fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl<F: Debug> Debug for File<F>

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

Formats the value using the given formatter.

impl<F: AsRawFd> Evented for File<F>

pub fn register(
    &self,
    poll: &Poll,
    token: Token,
    interest: Ready,
    opts: PollOpt
) -> Result<()>

Register self with the given Poll instance.

pub fn reregister(
    &self,
    poll: &Poll,
    token: Token,
    interest: Ready,
    opts: PollOpt
) -> Result<()>

Re-register self with the given Poll instance.

pub fn deregister(&self, poll: &Poll) -> Result<()>

Deregister self from the given Poll instance

impl<F: Read> Read for File<F>

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

pub fn read_vectored(
    &mut self,
    bufs: &mut [IoSliceMut<'_>]
) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

pub fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

pub unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

pub fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

pub fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

pub fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

pub fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

pub fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

pub fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

pub fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl<F: Seek> Seek for File<F>

pub fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

pub fn stream_len(&mut self) -> Result<u64, Error>

🔬 This is a nightly-only experimental API. (seek_convenience)

Returns the length of this stream (in bytes).

pub fn stream_position(&mut self) -> Result<u64, Error>

🔬 This is a nightly-only experimental API. (seek_convenience)

Returns the current seek position from the start of the stream.

impl<F: Write> Write for File<F>

pub fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

pub fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

pub fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

pub fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

pub fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

pub fn write_all_vectored(
    &mut self,
    bufs: &mut [IoSlice<'_>]
) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

pub fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

pub fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.