Struct tokio::net::windows::named_pipe::NamedPipeClient [−][src]
pub struct NamedPipeClient { /* fields omitted */ }
net
only.Expand description
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 winapi::shared::winerror; 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(winerror::ERROR_PIPE_BUSY as i32) => (), Err(e) => return Err(e), } time::sleep(Duration::from_millis(50)).await; }; /* use the connected client */
Implementations
Construct 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.
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);
Wait 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.
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()); } } } } }
Wait 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(()) }
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
.
Try 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. 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; 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(()) }
Try 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(()) }
Wait 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(()) }
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
.
Try 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(()) }
Try 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(()) }
Trait Implementations
Attempt to write bytes from buf
into the object. Read more
Like poll_write
, except that it writes from a slice of buffers. Read more
Attempts to flush the object, ensuring that any buffered data reach their destination. Read more
Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down. Read more
Determines if this writer has an efficient poll_write_vectored
implementation. Read more
Auto Trait Implementations
impl !RefUnwindSafe for NamedPipeClient
impl Send for NamedPipeClient
impl Sync for NamedPipeClient
impl Unpin for NamedPipeClient
impl !UnwindSafe for NamedPipeClient