Структура NamedPipeClient

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

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

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

Ошибки

Функция завершится ошибкой, если вызвать её вне среды выполнения Tokio, в среде выполнения, где не включён ввод-вывод, или если произойдёт какая-либо ошибка ввода-вывода, специфичная для ОС.

Получает сведения об именованном канале, с которым связан клиент.

use tokio::net::windows::named_pipe::{ClientOptions, PipeEnd, PipeMode};

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-info";

let client = ClientOptions::new()
    .open(PIPE_NAME)?;

let client_info = client.info()?;

assert_eq!(client_info.end, PipeEnd::Client);
assert_eq!(client_info.mode, PipeMode::Message);
assert_eq!(client_info.max_instances, 5);

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

Эта функция обычно используется вместе с try_read() или try_write(). Она позволяет выполнять чтение и запись в один канал одновременно в рамках одной задачи, не разделяя канал.

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

Примеры

Одновременное чтение из канала и запись в него в рамках одной задачи без разделения.

use tokio::io::Interest;
use tokio::net::windows::named_pipe;
use std::error::Error;
use std::io;

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-ready";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = named_pipe::ClientOptions::new().open(PIPE_NAME)?;

    loop {
        let ready = client.ready(Interest::READABLE | Interest::WRITABLE).await?;

        if ready.is_readable() {
            let mut data = vec![0; 1024];
            // Try to read data, this may still fail with `WouldBlock`
            // if the readiness event is a false positive.
            match client.try_read(&mut data) {
                Ok(n) => {
                    println!("read {} bytes", n);
                }
                Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
                    continue;
                }
                Err(e) => {
                    return Err(e.into());
                }
            }
        }

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

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

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

Примеры

use tokio::net::windows::named_pipe;
use std::error::Error;
use std::io;

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-readable";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = named_pipe::ClientOptions::new().open(PIPE_NAME)?;

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

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

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match client.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 будет вызван Waker::wake.

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

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

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

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

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

Ошибки

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

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

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

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

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

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

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

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

Примеры

use tokio::net::windows::named_pipe;
use std::error::Error;
use std::io;

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-try-read";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = named_pipe::ClientOptions::new().open(PIPE_NAME)?;

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

        // Creating the buffer **after** the `await` prevents it from
        // being stored in the async task.
        let mut buf = [0; 4096];

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match client.try_read(&mut buf) {
            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(())
}

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

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

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

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

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

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

Примеры

use tokio::net::windows::named_pipe;
use std::error::Error;
use std::io::{self, IoSliceMut};

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-try-read-vectored";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = named_pipe::ClientOptions::new().open(PIPE_NAME)?;

    loop {
        // Wait for the pipe to be readable
        client.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 = [
            IoSliceMut::new(&mut buf_a),
            IoSliceMut::new(&mut buf_b),
        ];

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match client.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(())
}

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

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

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

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

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

Примеры

use tokio::net::windows::named_pipe;
use std::error::Error;
use std::io;

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-readable";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = named_pipe::ClientOptions::new().open(PIPE_NAME)?;

    loop {
        // Wait for the pipe to be readable
        client.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 client.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(())
}

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

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

Примеры

use tokio::net::windows::named_pipe;
use std::error::Error;
use std::io;

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-writable";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = named_pipe::ClientOptions::new().open(PIPE_NAME)?;

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

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match client.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, переданного при последнем вызове. (Однако poll_read_ready сохраняет второй, независимый waker.)

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

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

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

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

Ошибки

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

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

Функция попытается записать всё содержимое buf, однако может быть записана только часть буфера.

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

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

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

Примеры

use tokio::net::windows::named_pipe;
use std::error::Error;
use std::io;

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-try-write";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = named_pipe::ClientOptions::new().open(PIPE_NAME)?;

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

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match client.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() с объединёнными буферами.

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

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

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

Примеры

use tokio::net::windows::named_pipe;
use std::error::Error;
use std::io;

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-try-write-vectored";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = named_pipe::ClientOptions::new().open(PIPE_NAME)?;

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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