Struct tokio::net::windows::named_pipe::NamedPipeClient

pub struct NamedPipeClient { /* private fields */ }

Available on Windows and crate feature net only.

A Windows named pipe client.

Constructed using ClientOptions::open.

Connecting a client correctly involves a few steps. When connecting through ClientOptions::open, it might error indicating one of two things:

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

So a correctly implemented client looks like this:

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

Implementations

impl NamedPipeClient

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

Constructs a new named pipe client 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 client is associated with.

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>

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

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

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

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

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

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

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

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

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

Trait Implementations

impl AsRawHandle for NamedPipeClient

fn as_raw_handle(&self) -> RawHandle

See std::os::windows::io::FromRawHandle::from_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

Formats the value using the given formatter.