Struct tokio::net::windows::named_pipe::NamedPipeServer

pub struct NamedPipeServer { /* private fields */ }

A Windows named pipe server.

Accepting client connections involves creating a server with ServerOptions::create and waiting for clients to connect using NamedPipeServer::connect.

To avoid having clients sporadically fail with std::io::ErrorKind::NotFound when they connect to a server, we must ensure that at least one server instance is available at all times. This means that the typical listen loop for a server is a bit involved, because we have to ensure that we never drop a server accidentally while a client might connect.

So a correctly implemented server looks like this:

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.
        let connected = server.connect().await?;

        // 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 */

Implementations

impl NamedPipeServer

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

Construct a new named pipe server from the specified raw handle.

This function will consume ownership of the handle given, passing responsibility for closing the handle to the returned object.

This function is also unsafe as the primitives currently returned have the contract that they are the sole owner of the file descriptor they are wrapping. Usage of this function could accidentally allow violating this contract which can cause memory unsafety in code that relies on it being true.

Errors

This errors if called outside of a Tokio Runtime, or in a runtime that has not enabled I/O, or if any OS-specific I/O errors occur.

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

Retrieves information about the named pipe the server is associated with.

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

Enables a named pipe server process to wait for a client process to connect to an instance of a named pipe. A client process connects by creating a named pipe with the same name.

This corresponds to the ConnectNamedPipe system call.

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

Disconnects the server end of a named pipe instance from a client process.

use tokio::io::AsyncWriteExt;
use tokio::net::windows::named_pipe::{ClientOptions, ServerOptions};
use winapi::shared::winerror;

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(winerror::ERROR_PIPE_NOT_CONNECTED as i32));

Trait Implementations

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

Formats the value using the given formatter.