Структура NamedPipeServer

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

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

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

Ошибки

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

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

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

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

let server = ServerOptions::new()
    .pipe_mode(PipeMode::Message)
    .max_instances(5)
    .create(PIPE_NAME)?;

let server_info = server.info()?;

assert_eq!(server_info.end, PipeEnd::Server);
assert_eq!(server_info.mode, PipeMode::Message);
assert_eq!(server_info.max_instances, 5);

Позволяет процессу сервера именованного канала ожидать подключения клиентского процесса к экземпляру именованного канала. Клиентский процесс подключается, создавая именованный канал с тем же именем.

Это соответствует системному вызову ConnectNamedPipe.

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

Этот метод безопасен при отмене. Если он используется в качестве ветви в select! и первой завершается другая ветвь, события подключения не теряются.

Пример

use tokio::net::windows::named_pipe::ServerOptions;

const PIPE_NAME: &str = r"\\.\pipe\mynamedpipe";

let pipe = ServerOptions::new().create(PIPE_NAME)?;

// Wait for a client to connect.
pipe.connect().await?;

// Use the connected client...

Отключает серверную сторону экземпляра именованного канала от клиентского процесса.

use tokio::io::AsyncWriteExt;
use tokio::net::windows::named_pipe::{ClientOptions, ServerOptions};
use windows_sys::Win32::Foundation::ERROR_PIPE_NOT_CONNECTED;

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

let server = ServerOptions::new()
    .create(PIPE_NAME)?;

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

// Wait for a client to become connected.
server.connect().await?;

// Forcibly disconnect the client.
server.disconnect()?;

// Write fails with an OS-specific error after client has been
// disconnected.
let e = client.write(b"ping").await.unwrap_err();
assert_eq!(e.raw_os_error(), Some(ERROR_PIPE_NOT_CONNECTED as i32));

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

Эта функция обычно используется вместе с 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-server-ready";

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

    loop {
        let ready = server.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 server.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 server.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-server-readable";

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

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

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

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match server.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-server-try-read";

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

    loop {
        // Wait for the pipe to be readable
        server.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 server.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-server-try-read-vectored";

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

    loop {
        // Wait for the pipe to be readable
        server.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 server.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 server = named_pipe::ServerOptions::new().create(PIPE_NAME)?;

    loop {
        // Wait for the pipe to be readable
        server.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 server.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-server-writable";

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

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

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match server.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::wake.

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

Эта функция предназначена для случаев, когда невозможно создать и закрепить 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-server-try-write";

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

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

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match server.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-server-try-write-vectored";

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

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

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

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match server.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 NamedPipeServer, поскольку это нарушит работу флага готовности и может привести к неправильной работе канала.

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

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

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

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

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

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

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

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

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

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