Struct NamedPipeServer

pub struct NamedPipeServer { /* private fields */ }

Available on Windows 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 compio_fs::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.
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 = compio_runtime::spawn(async move {
        // use the connected client
    });
}

Implementations

impl NamedPipeServer

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

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

use compio_fs::named_pipe::{PipeEnd, PipeMode, ServerOptions};

const PIPE_NAME: &str = r"\\.\pipe\compio-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.

Example

use compio_fs::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 compio_fs::named_pipe::{ClientOptions, ServerOptions};
use compio_io::AsyncWrite;
use windows_sys::Win32::Foundation::ERROR_PIPE_NOT_CONNECTED;

const PIPE_NAME: &str = r"\\.\pipe\compio-named-pipe-disconnect";

let server = ServerOptions::new().create(PIPE_NAME).unwrap();

let mut client = ClientOptions::new().open(PIPE_NAME).await.unwrap();

// Wait for a client to become connected.
server.connect().await.unwrap();

// Forcibly disconnect the client.
server.disconnect().unwrap();

// Write fails with an OS-specific error after client has been
// disconnected.
let e = client.write("ping").await.0.unwrap();
assert_eq!(e, 0);

Trait Implementations

impl AsRawFd for NamedPipeServer

fn as_raw_fd(&self) -> RawFd

Extracts the raw fd.

impl AsRawHandle for NamedPipeServer

fn as_raw_handle(&self) -> RawHandle

Extracts the raw handle.

impl AsyncRead for &NamedPipeServer

async fn read<B: IoBufMut>(&mut self, buffer: B) -> BufResult<usize, B>

Read some bytes from this source into the IoBufMut buffer and return a BufResult, consisting of the buffer and a usize indicating how many bytes were read.

async fn read_vectored<V>(&mut self, buf: V) -> BufResult<usize, V>

where V: IoVectoredBufMut,

Like read, except that it reads into a type implements IoVectoredBufMut.

impl AsyncRead for NamedPipeServer

async fn read<B: IoBufMut>(&mut self, buf: B) -> BufResult<usize, B>

Read some bytes from this source into the IoBufMut buffer and return a BufResult, consisting of the buffer and a usize indicating how many bytes were read.

async fn read_vectored<V>(&mut self, buf: V) -> BufResult<usize, V>

where V: IoVectoredBufMut,

Like read, except that it reads into a type implements IoVectoredBufMut.

impl AsyncWrite for &NamedPipeServer

async fn write<T: IoBuf>(&mut self, buffer: T) -> BufResult<usize, T>

Write some bytes from the buffer into this source and return a BufResult, consisting of the buffer and a usize indicating how many bytes were written.

async fn flush(&mut self) -> Result<()>

Attempts to flush the object, ensuring that any buffered data reach their destination.

async fn shutdown(&mut self) -> Result<()>

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

async fn write_vectored<T>(&mut self, buf: T) -> BufResult<usize, T>

where T: IoVectoredBuf,

Like write, except that it write bytes from a buffer implements IoVectoredBuf into the source.

impl AsyncWrite for NamedPipeServer

async fn write<T: IoBuf>(&mut self, buf: T) -> BufResult<usize, T>

Write some bytes from the buffer into this source and return a BufResult, consisting of the buffer and a usize indicating how many bytes were written.

async fn flush(&mut self) -> Result<()>

Attempts to flush the object, ensuring that any buffered data reach their destination.

async fn shutdown(&mut self) -> Result<()>

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

async fn write_vectored<T>(&mut self, buf: T) -> BufResult<usize, T>

where T: IoVectoredBuf,

Like write, except that it write bytes from a buffer implements IoVectoredBuf into the source.

impl Clone for NamedPipeServer

fn clone(&self) -> NamedPipeServer

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NamedPipeServer

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

Formats the value using the given formatter.

impl FromRawHandle for NamedPipeServer

unsafe fn from_raw_handle(handle: RawHandle) -> Self

Constructs a new I/O object from the specified raw handle.

impl ToSharedFd<File> for NamedPipeServer

fn to_shared_fd(&self) -> SharedFd<File>

Return a cloned SharedFd.