结构体 NamedPipeClient 

pub struct NamedPipeClient { /* private fields */ }

一个 Windows 命名管道 客户端。

使用 ClientOptions::open 构造。

正确连接客户端涉及几个步骤。当通过 ClientOptions::open 进行连接时，可能会以两种错误之一报错：

• std::io::ErrorKind::NotFound - There is no server available.
• ERROR_PIPE_BUSY - There is a server available, but it is busy. Sleep for a while and try again.

因此，一个正确实现的客户端看起来如下：

use std::time::Duration;
use tokio::net::windows::named_pipe::ClientOptions;
use tokio::time;
use windows_sys::Win32::Foundation::ERROR_PIPE_BUSY;

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

let client = loop {
    match ClientOptions::new().open(PIPE_NAME) {
        Ok(client) => break client,
        Err(e) if e.raw_os_error() == Some(ERROR_PIPE_BUSY as i32) => (),
        Err(e) => return Err(e),
    }

    time::sleep(Duration::from_millis(50)).await;
};

/* use the connected client */

实现

impl NamedPipeClient

pub unsafe fn from_raw_handle(handle: RawHandle) -> Result<Self>

从指定的原始句柄构造一个新的命名管道客户端。

此函数将接管所给定句柄的所有权，将关闭该句柄的责任转交给返回的对象。

此函数也是不安全的，因为目前返回的原语具有“它们是其包装的文件描述符的唯一所有者”的约定。使用此函数可能会无意中违反该约定，从而在依赖此约定的代码中导致内存不安全。

Errors

如果在 Tokio 运行时 之外被调用，或者在未启用 I/O的运行时中调用，或者发生任何操作系统特有的 I/O 错误，则此函数会出错。

pub fn info(&self) -> Result<PipeInfo>

获取客户端所关联的命名管道的信息。

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);

pub async fn ready(&self, interest: Interest) -> Result<Ready>

等待任意一个所请求的就绪状态。

该函数通常与 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());
                }
            }
        }
    }
}

pub async fn readable(&self) -> Result<()>

等待管道变为可读。

该函数等同于 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(())
}

pub fn poll_read_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Poll 读取就绪状态。

如果管道当前尚未准备好读取，此方法会存储提供的 Context 中 Waker 的一个克隆。当管道变为可读时，会在该 waker 上调用 Waker::wake。

请注意，对于 poll_read_ready 或 poll_read 的多次调用，仅会调度传递给最近一次调用的 Context 中的 Waker 接收唤醒。（不过，poll_write_ready 仍保留一个独立的 waker。）

该函数用于不便通过 readable 创建并固定一个 future 的场景。在条件允许时，建议使用 readable，因为它支持同时从多个任务进行 poll。

Return value

函数返回：

• Poll::Pending if the pipe is not ready for reading.
• Poll::Ready(Ok(())) if the pipe is ready for reading.
• Poll::Ready(Err(e)) if an error is encountered.

Errors

该函数可能会遇到除 WouldBlock 之外的任何标准 I/O 错误。

pub fn try_read(&self, buf: &mut [u8]) -> Result<usize>

尝试从管道读取数据到所提供的缓冲区，并返回已读取的字节数。

从管道接收任何已有数据，但不会等待新数据的到达。成功时返回已读取的字节数。由于 try_read() 是非阻塞的，缓冲区不必由异步任务持有，可以完全存在于栈上。

通常，readable() 或 ready() 与该函数配合使用。

Return

如果成功读取数据，则返回 Ok(n)，其中 n 是已读取的字节数。如果 n 为 0，则可能表示以下两种情况之一：

1. The pipe’s read half is closed and will no longer yield data.
2. The specified buffer was 0 bytes in length.

如果管道尚未准备好读取数据，则返回 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(())
}

pub fn try_read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

尝试从管道读取数据到所提供的多个缓冲区中，并返回已读取的字节数。

数据依次拷贝填充到每个缓冲区中，最后一个缓冲区可能只被部分填充。此方法等效于对拼接后的缓冲区进行一次 try_read() 调用。

从管道接收任何已有数据，但不会等待新数据的到达。成功时返回已读取的字节数。由于 try_read_vectored() 是非阻塞的，缓冲区不必由异步任务持有，可以完全存在于栈上。

通常，readable() 或 ready() 与该函数配合使用。

Return

如果成功读取数据，则返回 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(())
}

pub fn try_read_buf<B: BufMut>(&self, buf: &mut B) -> Result<usize>

尝试从流读取数据到所提供的缓冲区中，并推进缓冲区的内部游标，返回读取的字节数。

从管道接收任何已有数据，但不会等待新数据的到达。成功时返回已读取的字节数。由于 try_read_buf() 是非阻塞的，缓冲区不必由异步任务持有，可以完全存在于栈上。

通常，readable() 或 ready() 与该函数配合使用。

Return

如果成功读取数据，则返回 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(())
}

pub async fn writable(&self) -> Result<()>

等待管道变为可写。

该函数等同于 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(())
}

pub fn poll_write_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Poll 写入就绪状态。

如果管道当前尚未准备好写入，此方法会存储提供的 Context 中 Waker 的一个克隆。当管道变为可写时，会在该 waker 上调用 Waker::wake。

请注意，对于 poll_write_ready 或 poll_write 的多次调用，仅会调度传递给最近一次调用的 Context 中的 Waker 接收唤醒。（不过，poll_read_ready 仍保留一个独立的 waker。）

该函数用于不便通过 writable 创建并固定一个 future 的场景。在条件允许时，建议使用 writable，因为它支持同时从多个任务进行 poll。

Return value

函数返回：

• Poll::Pending if the pipe is not ready for writing.
• Poll::Ready(Ok(())) if the pipe is ready for writing.
• Poll::Ready(Err(e)) if an error is encountered.

Errors

该函数可能会遇到除 WouldBlock 之外的任何标准 I/O 错误。

pub fn try_write(&self, buf: &[u8]) -> Result<usize>

尝试将一个缓冲区写入管道，并返回已写入的字节数。

该函数会尝试写入 buf 的全部内容，但可能只会写入缓冲区的一部分。

该函数通常与 writable() 配合使用。

Return

如果数据成功写入，则返回 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(())
}

pub fn try_write_vectored(&self, buf: &[IoSlice<'_>]) -> Result<usize>

尝试将多个缓冲区写入管道，并返回已写入的字节数。

数据从每个缓冲区依次写入，最后一个缓冲区可能仅被部分消费。此方法等效于对拼接后的缓冲区进行一次 try_write() 调用。

该函数通常与 writable() 配合使用。

Return

如果数据成功写入，则返回 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(())
}

pub fn try_io<R>( &self, interest: Interest, f: impl FnOnce() -> Result<R>, ) -> Result<R>

尝试使用用户提供的 IO 操作对管道进行读或写。

如果管道就绪，则调用所提供的闭包。闭包应通过手动调用适当的系统调用来尝试对管道执行 IO 操作。如果由于管道实际上未就绪而导致操作失败，则闭包应返回 WouldBlock 错误，并清除就绪标志。然后 try_io 返回闭包的返回值。

如果管道尚未就绪，则不会调用闭包，并返回 WouldBlock 错误。

闭包只有在执行了因管道未就绪而失败的 IO 操作时，才应返回 WouldBlock 错误。在其他情况下返回 WouldBlock 错误会错误地清除就绪标志，可能导致管道行为异常。

闭包不应使用 Tokio NamedPipeClient 类型上定义的任何方法来执行 IO 操作，因为这会干扰就绪标志，并可能导致管道行为异常。

该方法不应与组合的 interest 一起使用。闭包应仅执行一种 IO 操作，因此不应需要多于一个就绪状态。如果使用组合的 interest 调用此方法，它可能会 panic 或永远睡眠。

通常，readable()、writable() 或 ready() 与该函数配合使用。

pub async fn async_io<R>( &self, interest: Interest, f: impl FnMut() -> Result<R>, ) -> Result<R>

使用用户提供的 IO 操作对管道进行读或写。

等待管道就绪，一旦就绪就调用所提供的闭包。闭包应通过手动调用适当的系统调用来尝试对管道执行 IO 操作。如果由于管道实际上未就绪而导致操作失败，则闭包应返回 WouldBlock 错误。此时就绪标志被清除，然后再次等待管道就绪。该循环会反复进行，直到闭包返回 Ok 或 WouldBlock 以外的错误。

闭包只有在执行了因管道未就绪而失败的 IO 操作时，才应返回 WouldBlock 错误。在其他情况下返回 WouldBlock 错误会错误地清除就绪标志，可能导致管道行为异常。

闭包不应使用 Tokio NamedPipeClient 类型上定义的任何方法来执行 IO 操作，因为这会干扰就绪标志，并可能导致管道行为异常。

该方法不应与组合的 interest 一起使用。闭包应仅执行一种 IO 操作，因此不应需要多于一个就绪状态。如果使用组合的 interest 调用此方法，它可能会 panic 或永远睡眠。

Trait 实现

impl AsHandle for NamedPipeClient

fn as_handle(&self) -> BorrowedHandle<'_>

Borrows the handle. 更多信息

impl AsRawHandle for NamedPipeClient

fn as_raw_handle(&self) -> RawHandle

Extracts the raw handle. 更多信息

impl AsyncRead for NamedPipeClient

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf. 更多信息

impl AsyncWrite for NamedPipeClient

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object. 更多信息

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Like poll_write, except that it writes from a slice of buffers. 更多信息

fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination. 更多信息

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down. 更多信息

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation. 更多信息

impl Debug for NamedPipeClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化器格式化此值。 更多信息