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

pub struct NamedPipeServer { /* private fields */ }

Available on Windows and crate feature net only.

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>

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

Cancel safety

This method is cancellation safe in the sense that if it is used as the event in a select! statement and some other branch completes first, then no connection events have been lost.

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

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

Waits for any of the requested ready states.

This function is usually paired with try_read() or try_write(). It can be used to concurrently read / write to the same pipe on a single task without splitting the pipe.

The function may complete without the pipe being ready. This is a false-positive and attempting an operation will return with io::ErrorKind::WouldBlock. The function can also return with an empty Ready set, so you should always check the returned value and possibly wait again if the requested states are not set.

Examples

Concurrently read and write to the pipe on the same task without splitting.

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

Waits for the pipe to become readable.

This function is equivalent to ready(Interest::READABLE) and is usually paired with try_read().

Examples

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

Polls for read readiness.

If the pipe is not currently ready for reading, this method will store a clone of the Waker from the provided Context. When the pipe becomes ready for reading, Waker::wake will be called on the waker.

Note that on multiple calls to poll_read_ready or poll_read, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup. (However, poll_write_ready retains a second, independent waker.)

This function is intended for cases where creating and pinning a future via readable is not feasible. Where possible, using readable is preferred, as this supports polling from multiple tasks at once.

Return value

The function returns:

• 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

This function may encounter any standard I/O error except WouldBlock.

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

Tries to read data from the pipe into the provided buffer, returning how many bytes were read.

Receives any pending data from the pipe but does not wait for new data to arrive. On success, returns the number of bytes read. Because try_read() is non-blocking, the buffer does not have to be stored by the async task and can exist entirely on the stack.

Usually, readable() or ready() is used with this function.

Return

If data is successfully read, Ok(n) is returned, where n is the number of bytes read. If n is 0, then it can indicate one of two scenarios:

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

If the pipe is not ready to read data, Err(io::ErrorKind::WouldBlock) is returned.

Examples

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>

Tries to read data from the pipe into the provided buffers, returning how many bytes were read.

Data is copied to fill each buffer in order, with the final buffer written to possibly being only partially filled. This method behaves equivalently to a single call to try_read() with concatenated buffers.

Receives any pending data from the pipe but does not wait for new data to arrive. On success, returns the number of bytes read. Because try_read_vectored() is non-blocking, the buffer does not have to be stored by the async task and can exist entirely on the stack.

Usually, readable() or ready() is used with this function.

Return

If data is successfully read, Ok(n) is returned, where n is the number of bytes read. Ok(0) indicates the pipe’s read half is closed and will no longer yield data. If the pipe is not ready to read data Err(io::ErrorKind::WouldBlock) is returned.

Examples

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>

Available on crate feature io-util only.

Tries to read data from the stream into the provided buffer, advancing the buffer’s internal cursor, returning how many bytes were read.

Receives any pending data from the pipe but does not wait for new data to arrive. On success, returns the number of bytes read. Because try_read_buf() is non-blocking, the buffer does not have to be stored by the async task and can exist entirely on the stack.

Usually, readable() or ready() is used with this function.

Return

If data is successfully read, Ok(n) is returned, where n is the number of bytes read. Ok(0) indicates the stream’s read half is closed and will no longer yield data. If the stream is not ready to read data Err(io::ErrorKind::WouldBlock) is returned.

Examples

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

Waits for the pipe to become writable.

This function is equivalent to ready(Interest::WRITABLE) and is usually paired with try_write().

Examples

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

Polls for write readiness.

If the pipe is not currently ready for writing, this method will store a clone of the Waker from the provided Context. When the pipe becomes ready for writing, Waker::wake will be called on the waker.

Note that on multiple calls to poll_write_ready or poll_write, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup. (However, poll_read_ready retains a second, independent waker.)

This function is intended for cases where creating and pinning a future via writable is not feasible. Where possible, using writable is preferred, as this supports polling from multiple tasks at once.

Return value

The function returns:

• 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

This function may encounter any standard I/O error except WouldBlock.

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

Tries to write a buffer to the pipe, returning how many bytes were written.

The function will attempt to write the entire contents of buf, but only part of the buffer may be written.

This function is usually paired with writable().

Return

If data is successfully written, Ok(n) is returned, where n is the number of bytes written. If the pipe is not ready to write data, Err(io::ErrorKind::WouldBlock) is returned.

Examples

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>

Tries to write several buffers to the pipe, returning how many bytes were written.

Data is written from each buffer in order, with the final buffer read from possible being only partially consumed. This method behaves equivalently to a single call to try_write() with concatenated buffers.

This function is usually paired with writable().

Return

If data is successfully written, Ok(n) is returned, where n is the number of bytes written. If the pipe is not ready to write data, Err(io::ErrorKind::WouldBlock) is returned.

Examples

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>

Tries to read or write from the pipe using a user-provided IO operation.

If the pipe is ready, the provided closure is called. The closure should attempt to perform IO operation from the pipe by manually calling the appropriate syscall. If the operation fails because the pipe is not actually ready, then the closure should return a WouldBlock error and the readiness flag is cleared. The return value of the closure is then returned by try_io.

If the pipe is not ready, then the closure is not called and a WouldBlock error is returned.

The closure should only return a WouldBlock error if it has performed an IO operation on the pipe that failed due to the pipe not being ready. Returning a WouldBlock error in any other situation will incorrectly clear the readiness flag, which can cause the pipe to behave incorrectly.

The closure should not perform the IO operation using any of the methods defined on the Tokio NamedPipeServer type, as this will mess with the readiness flag and can cause the pipe to behave incorrectly.

This method is not intended to be used with combined interests. The closure should perform only one type of IO operation, so it should not require more than one ready state. This method may panic or sleep forever if it is called with a combined interest.

Usually, readable(), writable() or ready() is used with this function.

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

Reads or writes from the pipe using a user-provided IO operation.

The readiness of the pipe is awaited and when the pipe is ready, the provided closure is called. The closure should attempt to perform IO operation on the pipe by manually calling the appropriate syscall. If the operation fails because the pipe is not actually ready, then the closure should return a WouldBlock error. In such case the readiness flag is cleared and the pipe readiness is awaited again. This loop is repeated until the closure returns an Ok or an error other than WouldBlock.

The closure should only return a WouldBlock error if it has performed an IO operation on the pipe that failed due to the pipe not being ready. Returning a WouldBlock error in any other situation will incorrectly clear the readiness flag, which can cause the pipe to behave incorrectly.

The closure should not perform the IO operation using any of the methods defined on the Tokio NamedPipeServer type, as this will mess with the readiness flag and can cause the pipe to behave incorrectly.

This method is not intended to be used with combined interests. The closure should perform only one type of IO operation, so it should not require more than one ready state. This method may panic or sleep forever if it is called with a combined interest.

Trait Implementations

impl AsHandle for NamedPipeServer

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

See std::os::windows::io::AsHandle::as_handle

impl AsRawHandle for NamedPipeServer

fn as_raw_handle(&self) -> RawHandle

See std::os::windows::io::AsRawHandle::as_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.