Структура Receiver

Создаёт новый Receiver из File.

Эта функция предназначена для создания канала из File, представляющего специальный FIFO-файл. Она проверяет, является ли файл каналом и открыт ли он для чтения, устанавливает неблокирующий режим и выполняет преобразование.

Ошибки

Завершается ошибкой с io::ErrorKind::InvalidInput, если файл не является каналом или не открыт для чтения. Также функция завершается ошибкой при возникновении любой стандартной ошибки ОС.

Паники

Эта функция вызывает панику, если её вызывают вне среды выполнения с включённым вводом-выводом.

Обычно среда выполнения устанавливается неявно, когда эта функция вызывается из future, выполняемого средой выполнения tokio; в противном случае среду выполнения можно задать явно с помощью функции Runtime::enter.

Создаёт новый Receiver из OwnedFd.

Эта функция предназначена для создания канала из OwnedFd, представляющего анонимный канал или специальный FIFO-файл. Она проверяет, является ли файловый дескриптор каналом и открыт ли он для чтения, устанавливает неблокирующий режим и выполняет преобразование.

Ошибки

Завершается ошибкой с io::ErrorKind::InvalidInput, если файловый дескриптор не является каналом или не открыт для чтения. Также функция завершается ошибкой при возникновении любой стандартной ошибки ОС.

Паники

Эта функция вызывает панику, если её вызывают вне среды выполнения с включённым вводом-выводом.

Обычно среда выполнения устанавливается неявно, когда эта функция вызывается из future, выполняемого средой выполнения tokio; в противном случае среду выполнения можно задать явно с помощью функции Runtime::enter.

Создаёт новый Receiver из File без проверки свойств канала.

Эта функция предназначена для создания канала из File, представляющего специальный FIFO-файл. При преобразовании не проверяются свойства нижележащего файла; пользователь должен самостоятельно убедиться, что файл открыт для чтения, представляет собой канал и настроен в неблокирующем режиме.

Примеры

use tokio::net::unix::pipe;
use std::fs::OpenOptions;
use std::os::unix::fs::{FileTypeExt, OpenOptionsExt};

const FIFO_NAME: &str = "path/to/a/fifo";

let file = OpenOptions::new()
    .read(true)
    .custom_flags(libc::O_NONBLOCK)
    .open(FIFO_NAME)?;
if file.metadata()?.file_type().is_fifo() {
    let rx = pipe::Receiver::from_file_unchecked(file)?;
    /* use the Receiver */
}

Паники

Эта функция вызывает панику, если её вызывают вне среды выполнения с включённым вводом-выводом.

Обычно среда выполнения устанавливается неявно, когда эта функция вызывается из future, выполняемого средой выполнения tokio; в противном случае среду выполнения можно задать явно с помощью функции Runtime::enter.

Создаёт новый Receiver из OwnedFd без проверки свойств канала.

Эта функция предназначена для создания канала из OwnedFd, представляющего анонимный канал или специальный FIFO-файл. При преобразовании не проверяются свойства нижележащего канала; пользователь должен самостоятельно убедиться, что файловый дескриптор представляет читающий конец канала и что канал настроен в неблокирующем режиме.

Паники

Эта функция вызывает панику, если её вызывают вне среды выполнения с включённым вводом-выводом.

Обычно среда выполнения устанавливается неявно, когда эта функция вызывается из future, выполняемого средой выполнения tokio; в противном случае среду выполнения можно задать явно с помощью функции Runtime::enter.

Ожидает наступления любого из запрошенных состояний готовности.

Эту функцию можно использовать вместо readable(), чтобы проверить возвращённый набор состояний готовности на наличие событий Ready::READABLE и Ready::READ_CLOSED.

Функция может завершиться, даже если канал не готов. Это ложное срабатывание, и попытка выполнить операцию вернёт io::ErrorKind::WouldBlock. Функция также может вернуть пустой набор Ready, поэтому всегда проверяйте возвращённое значение и, возможно, ожидайте снова, если запрошенные состояния не установлены.

Безопасность при отмене

Этот метод безопасен при отмене. После возникновения события готовности метод будет немедленно возвращать результат, пока это событие готовности не будет обработано попыткой чтения, завершившейся с ошибкой WouldBlock или Poll::Pending.

Ожидает, пока канал не станет доступен для чтения.

Эта функция эквивалентна ready(Interest::READABLE) и обычно используется вместе с try_read().

Примеры

use tokio::net::unix::pipe;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Open a reading end of a fifo
    let rx = pipe::OpenOptions::new().open_receiver("path/to/a/fifo")?;

    let mut msg = vec![0; 1024];

    loop {
        // Wait for the pipe to be readable
        rx.readable().await?;

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match rx.try_read(&mut msg) {
            Ok(n) => {
                msg.truncate(n);
                break;
            }
            Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    println!("GOT = {:?}", msg);
    Ok(())
}

Проверяет готовность к чтению.

Если канал в данный момент не готов к чтению, этот метод сохранит копию Waker из переданного Context. Когда канал будет готов к чтению, для пробуждающего объекта будет вызван Waker::wake.

Обратите внимание: при нескольких вызовах poll_read_ready или poll_read пробуждение будет запланировано только для Waker из Context, переданного при последнем вызове.

Эта функция предназначена для случаев, когда создать и закрепить future с помощью readable невозможно. Если есть такая возможность, предпочтительно использовать readable, поскольку это позволяет выполнять опрос одновременно из нескольких задач.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если канал не готов к чтению.
• Poll::Ready(Ok(())), если канал готов к чтению.
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, кроме WouldBlock.

Пытается прочитать данные из канала в предоставленный буфер и возвращает количество прочитанных байтов.

Читает все ожидающие данные из канала, но не ждёт поступления новых. В случае успеха возвращает количество прочитанных байтов. Поскольку try_read() работает в неблокирующем режиме, буфер не нужно сохранять в асинхронной задаче, и он может целиком находиться в стеке.

Эта функция обычно используется вместе с readable().

Возвращаемое значение

Если данные прочитаны успешно, возвращается Ok(n), где n — количество прочитанных байтов. Если n равно 0, это может указывать на один из двух сценариев:

1. Записывающий конец канала закрыт и больше не будет записывать данные.
2. Длина указанного буфера равна 0 байт.

Если канал не готов к чтению данных, возвращается Err(io::ErrorKind::WouldBlock).

Примечания

Чтобы избежать ненужных системных вызовов, чтение будет предприниматься только в том случае, если ОС сообщила Tokio, что канал стал доступен для чтения. Поэтому try_read() может завершиться ошибкой WouldBlock, если Tokio ещё не получил от ОС уведомление о том, что канал стал доступен для чтения.

Примеры

use tokio::net::unix::pipe;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Open a reading end of a fifo
    let rx = pipe::OpenOptions::new().open_receiver("path/to/a/fifo")?;

    let mut msg = vec![0; 1024];

    loop {
        // Wait for the pipe to be readable
        rx.readable().await?;

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match rx.try_read(&mut msg) {
            Ok(n) => {
                msg.truncate(n);
                break;
            }
            Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    println!("GOT = {:?}", msg);
    Ok(())
}

Пытается прочитать данные из канала в предоставленные буферы и возвращает количество прочитанных байтов.

Данные копируются в буферы по порядку; последний буфер может быть заполнен лишь частично. Этот метод эквивалентен одному вызову try_read() с объединёнными буферами.

Считывает все ожидающие данные из канала, но не ждёт поступления новых данных. В случае успеха возвращает количество прочитанных байтов. Поскольку try_read_vectored() работает в неблокирующем режиме, буфер не требуется хранить в асинхронной задаче — он может целиком находиться в стеке.

Обычно эту функцию используют вместе с readable().

Возвращаемое значение

Если данные успешно прочитаны, возвращается Ok(n), где n — количество прочитанных байтов. Ok(0) означает, что записывающий конец канала закрыт и больше не будет записывать данные. Если канал не готов к чтению данных, возвращается Err(io::ErrorKind::WouldBlock).

Примечания

Чтобы избежать ненужных системных вызовов, операция чтения выполняется только в том случае, если ОС сообщила Tokio, что канал стал доступен для чтения. Поэтому try_read_vectored() может завершиться ошибкой WouldBlock, если Tokio ещё не получил от ОС уведомление о том, что канал стал доступен для чтения.

Примеры

use tokio::net::unix::pipe;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Open a reading end of a fifo
    let rx = pipe::OpenOptions::new().open_receiver("path/to/a/fifo")?;

    loop {
        // Wait for the pipe to be readable
        rx.readable().await?;

        // Creating the buffer **after** the `await` prevents it from
        // being stored in the async task.
        let mut buf_a = [0; 512];
        let mut buf_b = [0; 1024];
        let mut bufs = [
            io::IoSliceMut::new(&mut buf_a),
            io::IoSliceMut::new(&mut buf_b),
        ];

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match rx.try_read_vectored(&mut bufs) {
            Ok(0) => break,
            Ok(n) => {
                println!("read {} bytes", n);
            }
            Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Пытается выполнить чтение из сокета с помощью предоставленной пользователем операции ввода-вывода.

Если сокет готов, вызывается предоставленная замыкающая функция. Она должна попытаться выполнить операцию ввода-вывода над сокетом, вручную вызвав соответствующий системный вызов. Если операция завершается ошибкой, поскольку сокет фактически не готов, замыкающая функция должна вернуть ошибку WouldBlock, после чего флаг готовности сбрасывается. Затем try_io возвращает значение, возвращённое замыкающей функцией.

Если сокет не готов, замыкающая функция не вызывается, а возвращается ошибка WouldBlock.

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

Замыкающая функция не должна выполнять операцию ввода-вывода с помощью методов, определённых для типа Tokio pipe::Receiver, так как это нарушит работу флага готовности и может привести к неправильной работе сокета.

Обычно эту функцию используют вместе с readable() или ready().

Пытается прочитать данные из канала в предоставленный буфер, сдвигая его внутренний курсор, и возвращает количество прочитанных байтов.

Считывает все ожидающие данные из канала, но не ждёт поступления новых данных. В случае успеха возвращает количество прочитанных байтов. Поскольку try_read_buf() работает в неблокирующем режиме, буфер не требуется хранить в асинхронной задаче — он может целиком находиться в стеке.

Обычно эту функцию используют вместе с readable() или ready().

Возвращаемое значение

Если данные успешно прочитаны, возвращается Ok(n), где n — количество прочитанных байтов. Ok(0) означает, что записывающий конец канала закрыт и больше не будет записывать данные. Если канал не готов к чтению данных, возвращается Err(io::ErrorKind::WouldBlock).

Примечания

Чтобы избежать ненужных системных вызовов, операция чтения выполняется только в том случае, если ОС сообщила Tokio, что канал стал доступен для чтения. Поэтому try_read_buf() может завершиться ошибкой WouldBlock, если Tokio ещё не получил от ОС уведомление о том, что канал стал доступен для чтения.

Примеры

use tokio::net::unix::pipe;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Open a reading end of a fifo
    let rx = pipe::OpenOptions::new().open_receiver("path/to/a/fifo")?;

    loop {
        // Wait for the pipe to be readable
        rx.readable().await?;

        let mut buf = Vec::with_capacity(4096);

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match rx.try_read_buf(&mut buf) {
            Ok(0) => break,
            Ok(n) => {
                println!("read {} bytes", n);
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Преобразует канал в OwnedFd в блокирующем режиме.

Эта функция удалит этот конец канала из цикла обработки событий, установит для него блокирующий режим и выполнит преобразование.

Преобразует канал в OwnedFd в неблокирующем режиме.

Эта функция удалит этот конец канала из цикла обработки событий и выполнит преобразование. Возвращаемый файловый дескриптор будет работать в неблокирующем режиме.

Возвращает аргумент без изменений.

Вызывает U::from(self).

То есть это преобразование выполняет то, что выбирает реализация From<T> for U.