结构体 NamedPipeServer 

pub struct NamedPipeServer { /* private fields */ }

一个 Windows 命名管道 服务端。

接受客户端连接涉及使用 ServerOptions::create 创建服务器，然后使用 NamedPipeServer::connect 等待客户端进行连接。

为了避免客户端在连接到服务器时偶发失败并返回 std::io::ErrorKind::NotFound，我们必须确保在任意时刻都有至少一个服务器实例可用。这意味着典型的服务器监听循环要稍显复杂，因为我们必须在客户端可能连接的情况下，避免意外地丢弃服务器。

因此，一个正确实现的服务器看起来如下：

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

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

// The first server needs to be constructed early so that clients can
// be correctly connected. Otherwise calling .wait will cause the client to
// error.
//
// Here we also make use of `first_pipe_instance`, which will ensure that
// there are no other servers up and running already.
let mut server = ServerOptions::new()
    .first_pipe_instance(true)
    .create(PIPE_NAME)?;

// Spawn the server loop.
let server = tokio::spawn(async move {
    loop {
        // Wait for a client to connect.
        server.connect().await?;
        let connected_client = server;

        // Construct the next server to be connected before sending the one
        // we already have of onto a task. This ensures that the server
        // isn't closed (after it's done in the task) before a new one is
        // available. Otherwise the client might error with
        // `io::ErrorKind::NotFound`.
        server = ServerOptions::new().create(PIPE_NAME)?;

        let client = tokio::spawn(async move {
            /* use the connected client */
        });
    }

    Ok::<_, io::Error>(())
});

/* do something else not server related here */

实现

impl NamedPipeServer

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

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

使命名管道服务器进程能够等待客户端进程连接到命名管道的一个实例。客户端进程会通过创建同名命名管道来进行连接。

这对应于 ConnectNamedPipe 系统调用。

Cancel safety

就取消安全而言，如果此方法作为 select! 语句中的事件，而其他某个分支先完成，则可以保证没有连接事件丢失。

Example

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...

pub fn disconnect(&self) -> Result<()>

将命名管道实例的服务器端与客户端进程断开连接。

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

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

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-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(())
}

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-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(())
}

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-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(())
}

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 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(())
}

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-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(())
}

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-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(())
}

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-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(())
}

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 NamedPipeServer 类型上定义的任何方法来执行 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 NamedPipeServer 类型上定义的任何方法来执行 IO 操作，因为这会干扰就绪标志，并可能导致管道行为异常。

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

Trait 实现

impl AsHandle for NamedPipeServer

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

Borrows the handle. 更多信息

impl AsRawHandle for NamedPipeServer

fn as_raw_handle(&self) -> RawHandle

Extracts the raw handle. 更多信息

impl AsyncRead for NamedPipeServer

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 NamedPipeServer

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 NamedPipeServer

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

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