Структура Sender

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

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

Ошибки

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

Паники

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

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

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

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

Ошибки

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

Паники

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

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

Создаёт новый Sender из 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()
    .write(true)
    .custom_flags(libc::O_NONBLOCK)
    .open(FIFO_NAME)?;
if file.metadata()?.file_type().is_fifo() {
    let tx = pipe::Sender::from_file_unchecked(file)?;
    /* use the Sender */
}

Паники

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

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

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

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

Паники

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

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

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

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

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

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

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

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

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

Примеры

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

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

    loop {
        // Wait for the pipe to be writable
        tx.writable().await?;

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match tx.try_write(b"hello world") {
            Ok(n) => {
                break;
            }
            Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Проверяет готовность к записи.

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

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

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

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

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

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

Ошибки

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

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

Функция попытается записать всё содержимое buf, но может быть записана только часть буфера. Если длина buf не превышает PIPE_BUF (константа ОС, равная 4096 в Linux), запись гарантированно будет атомарной: либо будет записано всё содержимое buf, либо этот метод завершится ошибкой WouldBlock. Если buf больше PIPE_BUF, такой гарантии нет.

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

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

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

Примечания

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

Примеры

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

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

    loop {
        // Wait for the pipe to be writable
        tx.writable().await?;

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match tx.try_write(b"hello world") {
            Ok(n) => {
                break;
            }
            Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

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

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

Если суммарная длина буферов не превышает PIPE_BUF (константа ОС, в Linux — 4096), запись гарантированно выполняется атомарно: либо будет записано всё содержимое буферов, либо этот метод завершится ошибкой WouldBlock. Если суммарная длина буферов превышает PIPE_BUF, такой гарантии нет.

Обычно эта функция используется вместе с writable.

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

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

Примечания

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

Примеры

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

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

    let bufs = [io::IoSlice::new(b"hello "), io::IoSlice::new(b"world")];

    loop {
        // Wait for the pipe to be writable
        tx.writable().await?;

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match tx.try_write_vectored(&bufs) {
            Ok(n) => {
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

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

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

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