Модуль io

Трейты, вспомогательные средства и определения типов для асинхронного ввода-вывода.

Этот модуль — асинхронная версия std::io. В основном в нём определены два трейта: AsyncRead и AsyncWrite, представляющие собой асинхронные версии трейтов Read и Write из стандартной библиотеки.

AsyncRead и AsyncWrite

Подобно трейтам Read и Write из стандартной библиотеки, AsyncRead и AsyncWrite предоставляют наиболее общий интерфейс для чтения и записи данных. Однако, в отличие от трейтов стандартной библиотеки, они являются асинхронными — это означает, что чтение из типа tokio::io или запись в него передаст управление планировщику Tokio, если ввод-вывод не готов, вместо того чтобы блокировать выполнение. Это позволяет запускать другие задачи, пока выполняются операции ввода-вывода.

Ещё одно отличие состоит в том, что AsyncRead и AsyncWrite содержат только основные методы, необходимые для асинхронного чтения и записи. Вспомогательные методы определены в трейтах-расширениях AsyncReadExt и AsyncWriteExt. Эти трейты автоматически реализуются для всех значений, реализующих соответственно AsyncRead и AsyncWrite.

Конечным пользователям редко приходится напрямую взаимодействовать с AsyncRead и AsyncWrite. Вместо этого они используют асинхронные функции, определённые в трейтах-расширениях. Ожидается, что авторы библиотек будут реализовывать AsyncRead и AsyncWrite, чтобы предоставлять типы, работающие как потоки байтов.

Несмотря на эти различия, трейты Tokio AsyncRead и AsyncWrite можно использовать почти так же, как Read и Write из стандартной библиотеки. Большинство типов стандартной библиотеки, реализующих Read и Write, имеют асинхронные аналоги в tokio, реализующие AsyncRead и AsyncWrite, например File и TcpStream.

Например, в документации стандартной библиотеки Read вводится с помощью примера чтения байтов из std::fs::File. То же самое можно сделать с помощью tokio::fs::File:

use tokio::io::{self, AsyncReadExt};
use tokio::fs::File;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt").await?;
    let mut buffer = [0; 10];

    // read up to 10 bytes
    let n = f.read(&mut buffer).await?;

    println!("The bytes: {:?}", &buffer[..n]);
    Ok(())
}

Буферизованные средства чтения и записи

Интерфейсы на основе байтов неудобны и могут быть неэффективными, поскольку нам пришлось бы почти постоянно обращаться к операционной системе. Для решения этой проблемы std::io поддерживает буферизованные средства чтения и записи, и tokio::io тоже.

Tokio предоставляет асинхронную версию трейта std::io::BufRead — AsyncBufRead, а также асинхронные структуры BufReader и BufWriter, оборачивающие средства чтения и записи. Эти обёртки используют буфер, уменьшая количество вызовов и предоставляя более удобные методы для доступа именно к нужным данным.

Например, BufReader работает с трейтом AsyncBufRead, добавляя дополнительные методы для любого асинхронного средства чтения:

use tokio::io::{self, BufReader, AsyncBufReadExt};
use tokio::fs::File;

#[tokio::main]
async fn main() -> io::Result<()> {
    let f = File::open("foo.txt").await?;
    let mut reader = BufReader::new(f);
    let mut buffer = String::new();

    // read a line into buffer
    reader.read_line(&mut buffer).await?;

    println!("{}", buffer);
    Ok(())
}

BufWriter не добавляет новых способов записи — он лишь буферизует каждый вызов write. Однако, чтобы гарантировать запись всех буферизованных данных, необходимо вызвать метод сброса буфера у BufWriter.

use tokio::io::{self, BufWriter, AsyncWriteExt};
use tokio::fs::File;

#[tokio::main]
async fn main() -> io::Result<()> {
    let f = File::create("foo.txt").await?;
    {
        let mut writer = BufWriter::new(f);

        // Write a byte to the buffer.
        writer.write(&[42u8]).await?;

        // Flush the buffer before it goes out of scope.
        writer.flush().await?;

    } // Unless flushed or shut down, the contents of the buffer is discarded on drop.

    Ok(())
}

Реализация AsyncRead и AsyncWrite

Поскольку это трейты, мы можем реализовать AsyncRead и AsyncWrite и для собственных типов. Обратите внимание, что эти трейты следует реализовывать только для неблокирующих типов ввода-вывода, интегрированных с системой типов futures. Иными словами, эти типы никогда не должны блокировать поток; вместо этого текущая задача получает уведомление, когда ресурс ввода-вывода готов.

Преобразование в Stream/Sink и обратно

Часто бывает удобно инкапсулировать чтение и запись байтов в Stream или Sink данных.

Tokio предоставляет в крейте tokio-util простые обёртки для преобразования AsyncRead в Stream и обратно. См. ReaderStream и StreamReader.

Также доступны вспомогательные трейты, абстрагирующие асинхронную буферизацию, необходимую для создания собственных адаптеров кодирования и декодирования байтов в структурированные данные и обратно. Они позволяют преобразовать объект, реализующий AsyncRead/AsyncWrite, в Stream/Sink. См. Decoder и Encoder в модуле tokio-util::codec.

Стандартный ввод и вывод

Tokio предоставляет асинхронные API для стандартных потоков ввода, вывода и ошибок. Эти API очень похожи на предоставляемые std, но также реализуют AsyncRead и AsyncWrite.

Обратите внимание, что API стандартных потоков ввода-вывода необходимо использовать в контексте среды выполнения Tokio, поскольку для работы им нужны специфичные для Tokio функции. Вызов этих функций вне среды выполнения Tokio вызовет панику.

Реэкспорты std

Кроме того, Error, ErrorKind, Result и SeekFrom реэкспортируются из std::io для удобства использования.