pub struct UnixDatagram { /* private fields */ }
Expand description
An I/O object representing a Unix datagram socket.
A socket can be either named (associated with a filesystem path) or unnamed.
This type does not provide a split
method, because this functionality
can be achieved by wrapping the socket in an Arc
. Note that you do
not need a Mutex
to share the UnixDatagram
— an Arc<UnixDatagram>
is enough. This is because all of the methods take &self
instead of
&mut self
.
Note: named sockets are persisted even after the object is dropped and the program has exited, and cannot be reconnected. It is advised that you either check for and unlink the existing socket if it exists, or use a temporary file that is guaranteed to not already exist.
§Examples
Using named sockets, associated with a filesystem path:
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// We use a temporary directory so that the socket
// files left by the bound sockets will get cleaned up.
let tmp = tempdir()?;
// Bind each socket to a filesystem path
let tx_path = tmp.path().join("tx");
let tx = UnixDatagram::bind(&tx_path)?;
let rx_path = tmp.path().join("rx");
let rx = UnixDatagram::bind(&rx_path)?;
let bytes = b"hello world";
tx.send_to(bytes, &rx_path).await?;
let mut buf = vec![0u8; 24];
let (size, addr) = rx.recv_from(&mut buf).await?;
let dgram = &buf[..size];
assert_eq!(dgram, bytes);
assert_eq!(addr.as_pathname().unwrap(), &tx_path);
Using unnamed sockets, created as a pair
use tokio::net::UnixDatagram;
// Create the pair of sockets
let (sock1, sock2) = UnixDatagram::pair()?;
// Since the sockets are paired, the paired send/recv
// functions can be used
let bytes = b"hello world";
sock1.send(bytes).await?;
let mut buff = vec![0u8; 24];
let size = sock2.recv(&mut buff).await?;
let dgram = &buff[..size];
assert_eq!(dgram, bytes);
Implementations§
Source§impl UnixDatagram
impl UnixDatagram
Sourcepub async fn ready(&self, interest: Interest) -> Result<Ready>
pub async fn ready(&self, interest: Interest) -> Result<Ready>
Waits for any of the requested ready states.
This function is usually paired with try_recv()
or try_send()
. It
can be used to concurrently recv
/ send
to the same socket on a single
task without splitting the socket.
The function may complete without the socket 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.
§Cancel safety
This method is cancel safe. Once a readiness event occurs, the method
will continue to return immediately until the readiness event is
consumed by an attempt to read or write that fails with WouldBlock
or
Poll::Pending
.
§Examples
Concurrently receive from and send to the socket on the same task without splitting.
use tokio::io::Interest;
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
socket.connect(&server_path)?;
loop {
let ready = socket.ready(Interest::READABLE | Interest::WRITABLE).await?;
if ready.is_readable() {
let mut data = [0; 1024];
match socket.try_recv(&mut data[..]) {
Ok(n) => {
println!("received {:?}", &data[..n]);
}
// False-positive, continue
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {}
Err(e) => {
return Err(e);
}
}
}
if ready.is_writable() {
// Write some data
match socket.try_send(b"hello world") {
Ok(n) => {
println!("sent {} bytes", n);
}
// False-positive, continue
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {}
Err(e) => {
return Err(e);
}
}
}
}
}
Sourcepub async fn writable(&self) -> Result<()>
pub async fn writable(&self) -> Result<()>
Waits for the socket to become writable.
This function is equivalent to ready(Interest::WRITABLE)
and is
usually paired with try_send()
or try_send_to()
.
The function may complete without the socket being writable. This is a
false-positive and attempting a try_send()
will return with
io::ErrorKind::WouldBlock
.
§Cancel safety
This method is cancel safe. Once a readiness event occurs, the method
will continue to return immediately until the readiness event is
consumed by an attempt to write that fails with WouldBlock
or
Poll::Pending
.
§Examples
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
socket.connect(&server_path)?;
loop {
// Wait for the socket to be writable
socket.writable().await?;
// Try to send data, this may still fail with `WouldBlock`
// if the readiness event is a false positive.
match socket.try_send(b"hello world") {
Ok(n) => {
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
continue;
}
Err(e) => {
return Err(e);
}
}
}
Ok(())
}
Sourcepub fn poll_send_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>
pub fn poll_send_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>
Polls for write/send readiness.
If the socket is not currently ready for sending, this method will
store a clone of the Waker
from the provided Context
. When the socket
becomes ready for sending, Waker::wake
will be called on the
waker.
Note that on multiple calls to poll_send_ready
or poll_send
, only
the Waker
from the Context
passed to the most recent call is
scheduled to receive a wakeup. (However, poll_recv_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 socket is not ready for writing.Poll::Ready(Ok(()))
if the socket 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
.
Sourcepub async fn readable(&self) -> Result<()>
pub async fn readable(&self) -> Result<()>
Waits for the socket to become readable.
This function is equivalent to ready(Interest::READABLE)
and is usually
paired with try_recv()
.
The function may complete without the socket being readable. This is a
false-positive and attempting a try_recv()
will return with
io::ErrorKind::WouldBlock
.
§Cancel safety
This method is cancel safe. Once a readiness event occurs, the method
will continue to return immediately until the readiness event is
consumed by an attempt to read that fails with WouldBlock
or
Poll::Pending
.
§Examples
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
socket.connect(&server_path)?;
loop {
// Wait for the socket to be readable
socket.readable().await?;
// The buffer is **not** included in the async task and will
// only exist on the stack.
let mut buf = [0; 1024];
// Try to recv data, this may still fail with `WouldBlock`
// if the readiness event is a false positive.
match socket.try_recv(&mut buf) {
Ok(n) => {
println!("GOT {:?}", &buf[..n]);
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
continue;
}
Err(e) => {
return Err(e);
}
}
}
Ok(())
}
Sourcepub fn poll_recv_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>
pub fn poll_recv_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>
Polls for read/receive readiness.
If the socket is not currently ready for receiving, this method will
store a clone of the Waker
from the provided Context
. When the
socket becomes ready for reading, Waker::wake
will be called on the
waker.
Note that on multiple calls to poll_recv_ready
, poll_recv
or
poll_peek
, only the Waker
from the Context
passed to the most
recent call is scheduled to receive a wakeup. (However,
poll_send_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 socket is not ready for reading.Poll::Ready(Ok(()))
if the socket 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
.
Sourcepub fn bind<P>(path: P) -> Result<UnixDatagram>
pub fn bind<P>(path: P) -> Result<UnixDatagram>
Creates a new UnixDatagram
bound to the specified path.
§Examples
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// We use a temporary directory so that the socket
// files left by the bound sockets will get cleaned up.
let tmp = tempdir()?;
// Bind the socket to a filesystem path
let socket_path = tmp.path().join("socket");
let socket = UnixDatagram::bind(&socket_path)?;
Sourcepub fn pair() -> Result<(UnixDatagram, UnixDatagram)>
pub fn pair() -> Result<(UnixDatagram, UnixDatagram)>
Creates an unnamed pair of connected sockets.
This function will create a pair of interconnected Unix sockets for communicating back and forth between one another.
§Examples
use tokio::net::UnixDatagram;
// Create the pair of sockets
let (sock1, sock2) = UnixDatagram::pair()?;
// Since the sockets are paired, the paired send/recv
// functions can be used
let bytes = b"hail eris";
sock1.send(bytes).await?;
let mut buff = vec![0u8; 24];
let size = sock2.recv(&mut buff).await?;
let dgram = &buff[..size];
assert_eq!(dgram, bytes);
Sourcepub fn from_std(datagram: UnixDatagram) -> Result<UnixDatagram>
pub fn from_std(datagram: UnixDatagram) -> Result<UnixDatagram>
Creates new UnixDatagram
from a std::os::unix::net::UnixDatagram
.
This function is intended to be used to wrap a UnixDatagram
from the
standard library in the Tokio equivalent.
§Notes
The caller is responsible for ensuring that the socket is in
non-blocking mode. Otherwise all I/O operations on the socket
will block the thread, which will cause unexpected behavior.
Non-blocking mode can be set using set_nonblocking
.
§Panics
This function panics if it is not called from within a runtime with IO enabled.
The runtime is usually set implicitly when this function is called
from a future driven by a Tokio runtime, otherwise runtime can be set
explicitly with Runtime::enter
function.
§Examples
use tokio::net::UnixDatagram;
use std::os::unix::net::UnixDatagram as StdUDS;
use tempfile::tempdir;
// We use a temporary directory so that the socket
// files left by the bound sockets will get cleaned up.
let tmp = tempdir()?;
// Bind the socket to a filesystem path
let socket_path = tmp.path().join("socket");
let std_socket = StdUDS::bind(&socket_path)?;
std_socket.set_nonblocking(true)?;
let tokio_socket = UnixDatagram::from_std(std_socket)?;
Sourcepub fn into_std(self) -> Result<UnixDatagram>
pub fn into_std(self) -> Result<UnixDatagram>
Turns a tokio::net::UnixDatagram
into a std::os::unix::net::UnixDatagram
.
The returned std::os::unix::net::UnixDatagram
will have nonblocking
mode set as true
. Use set_nonblocking
to change the blocking mode
if needed.
§Examples
let tokio_socket = tokio::net::UnixDatagram::bind("/path/to/the/socket")?;
let std_socket = tokio_socket.into_std()?;
std_socket.set_nonblocking(false)?;
Sourcepub fn unbound() -> Result<UnixDatagram>
pub fn unbound() -> Result<UnixDatagram>
Creates a new UnixDatagram
which is not bound to any address.
§Examples
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// Create an unbound socket
let tx = UnixDatagram::unbound()?;
// Create another, bound socket
let tmp = tempdir()?;
let rx_path = tmp.path().join("rx");
let rx = UnixDatagram::bind(&rx_path)?;
// Send to the bound socket
let bytes = b"hello world";
tx.send_to(bytes, &rx_path).await?;
let mut buf = vec![0u8; 24];
let (size, addr) = rx.recv_from(&mut buf).await?;
let dgram = &buf[..size];
assert_eq!(dgram, bytes);
Sourcepub fn connect<P: AsRef<Path>>(&self, path: P) -> Result<()>
pub fn connect<P: AsRef<Path>>(&self, path: P) -> Result<()>
Connects the socket to the specified address.
The send
method may be used to send data to the specified address.
recv
and recv_from
will only receive data from that address.
§Examples
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// Create an unbound socket
let tx = UnixDatagram::unbound()?;
// Create another, bound socket
let tmp = tempdir()?;
let rx_path = tmp.path().join("rx");
let rx = UnixDatagram::bind(&rx_path)?;
// Connect to the bound socket
tx.connect(&rx_path)?;
// Send to the bound socket
let bytes = b"hello world";
tx.send(bytes).await?;
let mut buf = vec![0u8; 24];
let (size, addr) = rx.recv_from(&mut buf).await?;
let dgram = &buf[..size];
assert_eq!(dgram, bytes);
Sourcepub async fn send(&self, buf: &[u8]) -> Result<usize>
pub async fn send(&self, buf: &[u8]) -> Result<usize>
Sends data on the socket to the socket’s peer.
§Cancel safety
This method is cancel safe. If send
is used as the event in a
tokio::select!
statement and some other branch
completes first, then it is guaranteed that the message was not sent.
§Examples
use tokio::net::UnixDatagram;
// Create the pair of sockets
let (sock1, sock2) = UnixDatagram::pair()?;
// Since the sockets are paired, the paired send/recv
// functions can be used
let bytes = b"hello world";
sock1.send(bytes).await?;
let mut buff = vec![0u8; 24];
let size = sock2.recv(&mut buff).await?;
let dgram = &buff[..size];
assert_eq!(dgram, bytes);
Sourcepub fn try_send(&self, buf: &[u8]) -> Result<usize>
pub fn try_send(&self, buf: &[u8]) -> Result<usize>
Tries to send a datagram to the peer without waiting.
§Examples
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
socket.connect(&server_path)?;
loop {
// Wait for the socket to be writable
socket.writable().await?;
// Try to send data, this may still fail with `WouldBlock`
// if the readiness event is a false positive.
match socket.try_send(b"hello world") {
Ok(n) => {
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
continue;
}
Err(e) => {
return Err(e);
}
}
}
Ok(())
}
Sourcepub fn try_send_to<P>(&self, buf: &[u8], target: P) -> Result<usize>
pub fn try_send_to<P>(&self, buf: &[u8], target: P) -> Result<usize>
Tries to send a datagram to the peer without waiting.
§Examples
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
loop {
// Wait for the socket to be writable
socket.writable().await?;
// Try to send data, this may still fail with `WouldBlock`
// if the readiness event is a false positive.
match socket.try_send_to(b"hello world", &server_path) {
Ok(n) => {
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
continue;
}
Err(e) => {
return Err(e);
}
}
}
Ok(())
}
Sourcepub async fn recv(&self, buf: &mut [u8]) -> Result<usize>
pub async fn recv(&self, buf: &mut [u8]) -> Result<usize>
Receives data from the socket.
§Cancel safety
This method is cancel safe. If recv
is used as the event in a
tokio::select!
statement and some other branch
completes first, it is guaranteed that no messages were received on this
socket.
§Examples
use tokio::net::UnixDatagram;
// Create the pair of sockets
let (sock1, sock2) = UnixDatagram::pair()?;
// Since the sockets are paired, the paired send/recv
// functions can be used
let bytes = b"hello world";
sock1.send(bytes).await?;
let mut buff = vec![0u8; 24];
let size = sock2.recv(&mut buff).await?;
let dgram = &buff[..size];
assert_eq!(dgram, bytes);
Sourcepub fn try_recv(&self, buf: &mut [u8]) -> Result<usize>
pub fn try_recv(&self, buf: &mut [u8]) -> Result<usize>
Tries to receive a datagram from the peer without waiting.
§Examples
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
socket.connect(&server_path)?;
loop {
// Wait for the socket to be readable
socket.readable().await?;
// The buffer is **not** included in the async task and will
// only exist on the stack.
let mut buf = [0; 1024];
// Try to recv data, this may still fail with `WouldBlock`
// if the readiness event is a false positive.
match socket.try_recv(&mut buf) {
Ok(n) => {
println!("GOT {:?}", &buf[..n]);
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
continue;
}
Err(e) => {
return Err(e);
}
}
}
Ok(())
}
Sourcepub fn try_recv_buf_from<B: BufMut>(
&self,
buf: &mut B,
) -> Result<(usize, SocketAddr)>
pub fn try_recv_buf_from<B: BufMut>( &self, buf: &mut B, ) -> Result<(usize, SocketAddr)>
Tries to receive data from the socket without waiting.
This method can be used even if buf
is uninitialized.
§Examples
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
loop {
// Wait for the socket to be readable
socket.readable().await?;
let mut buf = Vec::with_capacity(1024);
// Try to recv data, this may still fail with `WouldBlock`
// if the readiness event is a false positive.
match socket.try_recv_buf_from(&mut buf) {
Ok((n, _addr)) => {
println!("GOT {:?}", &buf[..n]);
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
continue;
}
Err(e) => {
return Err(e);
}
}
}
Ok(())
}
Sourcepub async fn recv_buf_from<B: BufMut>(
&self,
buf: &mut B,
) -> Result<(usize, SocketAddr)>
pub async fn recv_buf_from<B: BufMut>( &self, buf: &mut B, ) -> Result<(usize, SocketAddr)>
Receives from the socket, advances the buffer’s internal cursor and returns how many bytes were read and the origin.
This method can be used even if buf
is uninitialized.
§Examples
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// We use a temporary directory so that the socket
// files left by the bound sockets will get cleaned up.
let tmp = tempdir()?;
// Bind each socket to a filesystem path
let tx_path = tmp.path().join("tx");
let tx = UnixDatagram::bind(&tx_path)?;
let rx_path = tmp.path().join("rx");
let rx = UnixDatagram::bind(&rx_path)?;
let bytes = b"hello world";
tx.send_to(bytes, &rx_path).await?;
let mut buf = Vec::with_capacity(24);
let (size, addr) = rx.recv_buf_from(&mut buf).await?;
let dgram = &buf[..size];
assert_eq!(dgram, bytes);
assert_eq!(addr.as_pathname().unwrap(), &tx_path);
Sourcepub fn try_recv_buf<B: BufMut>(&self, buf: &mut B) -> Result<usize>
pub fn try_recv_buf<B: BufMut>(&self, buf: &mut B) -> Result<usize>
Tries to read data from the stream into the provided buffer, advancing the buffer’s internal cursor, returning how many bytes were read.
This method can be used even if buf
is uninitialized.
§Examples
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
socket.connect(&server_path)?;
loop {
// Wait for the socket to be readable
socket.readable().await?;
let mut buf = Vec::with_capacity(1024);
// Try to recv data, this may still fail with `WouldBlock`
// if the readiness event is a false positive.
match socket.try_recv_buf(&mut buf) {
Ok(n) => {
println!("GOT {:?}", &buf[..n]);
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
continue;
}
Err(e) => {
return Err(e);
}
}
}
Ok(())
}
Sourcepub async fn recv_buf<B: BufMut>(&self, buf: &mut B) -> Result<usize>
pub async fn recv_buf<B: BufMut>(&self, buf: &mut B) -> Result<usize>
Receives data from the socket from the address to which it is connected, advancing the buffer’s internal cursor, returning how many bytes were read.
This method can be used even if buf
is uninitialized.
§Examples
use tokio::net::UnixDatagram;
// Create the pair of sockets
let (sock1, sock2) = UnixDatagram::pair()?;
// Since the sockets are paired, the paired send/recv
// functions can be used
let bytes = b"hello world";
sock1.send(bytes).await?;
let mut buff = Vec::with_capacity(24);
let size = sock2.recv_buf(&mut buff).await?;
let dgram = &buff[..size];
assert_eq!(dgram, bytes);
Sourcepub async fn send_to<P>(&self, buf: &[u8], target: P) -> Result<usize>
pub async fn send_to<P>(&self, buf: &[u8], target: P) -> Result<usize>
Sends data on the socket to the specified address.
§Cancel safety
This method is cancel safe. If send_to
is used as the event in a
tokio::select!
statement and some other branch
completes first, then it is guaranteed that the message was not sent.
§Examples
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// We use a temporary directory so that the socket
// files left by the bound sockets will get cleaned up.
let tmp = tempdir()?;
// Bind each socket to a filesystem path
let tx_path = tmp.path().join("tx");
let tx = UnixDatagram::bind(&tx_path)?;
let rx_path = tmp.path().join("rx");
let rx = UnixDatagram::bind(&rx_path)?;
let bytes = b"hello world";
tx.send_to(bytes, &rx_path).await?;
let mut buf = vec![0u8; 24];
let (size, addr) = rx.recv_from(&mut buf).await?;
let dgram = &buf[..size];
assert_eq!(dgram, bytes);
assert_eq!(addr.as_pathname().unwrap(), &tx_path);
Sourcepub async fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>
pub async fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>
Receives data from the socket.
§Cancel safety
This method is cancel safe. If recv_from
is used as the event in a
tokio::select!
statement and some other branch
completes first, it is guaranteed that no messages were received on this
socket.
§Examples
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// We use a temporary directory so that the socket
// files left by the bound sockets will get cleaned up.
let tmp = tempdir()?;
// Bind each socket to a filesystem path
let tx_path = tmp.path().join("tx");
let tx = UnixDatagram::bind(&tx_path)?;
let rx_path = tmp.path().join("rx");
let rx = UnixDatagram::bind(&rx_path)?;
let bytes = b"hello world";
tx.send_to(bytes, &rx_path).await?;
let mut buf = vec![0u8; 24];
let (size, addr) = rx.recv_from(&mut buf).await?;
let dgram = &buf[..size];
assert_eq!(dgram, bytes);
assert_eq!(addr.as_pathname().unwrap(), &tx_path);
Sourcepub fn poll_recv_from(
&self,
cx: &mut Context<'_>,
buf: &mut ReadBuf<'_>,
) -> Poll<Result<SocketAddr>>
pub fn poll_recv_from( &self, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<SocketAddr>>
Attempts to receive a single datagram on the specified address.
Note that on multiple calls to a poll_*
method in the recv
direction, only the
Waker
from the Context
passed to the most recent call will be scheduled to
receive a wakeup.
§Return value
The function returns:
Poll::Pending
if the socket is not ready to readPoll::Ready(Ok(addr))
reads data fromaddr
intoReadBuf
if the socket is readyPoll::Ready(Err(e))
if an error is encountered.
§Errors
This function may encounter any standard I/O error except WouldBlock
.
Sourcepub fn poll_send_to<P>(
&self,
cx: &mut Context<'_>,
buf: &[u8],
target: P,
) -> Poll<Result<usize>>
pub fn poll_send_to<P>( &self, cx: &mut Context<'_>, buf: &[u8], target: P, ) -> Poll<Result<usize>>
Attempts to send data to the specified address.
Note that on multiple calls to a poll_*
method in the send direction, only the
Waker
from the Context
passed to the most recent call will be scheduled to
receive a wakeup.
§Return value
The function returns:
Poll::Pending
if the socket is not ready to writePoll::Ready(Ok(n))
n
is the number of bytes sent.Poll::Ready(Err(e))
if an error is encountered.
§Errors
This function may encounter any standard I/O error except WouldBlock
.
Sourcepub fn poll_send(&self, cx: &mut Context<'_>, buf: &[u8]) -> Poll<Result<usize>>
pub fn poll_send(&self, cx: &mut Context<'_>, buf: &[u8]) -> Poll<Result<usize>>
Attempts to send data on the socket to the remote address to which it
was previously connect
ed.
The connect
method will connect this socket to a remote address.
This method will fail if the socket is not connected.
Note that on multiple calls to a poll_*
method in the send direction,
only the Waker
from the Context
passed to the most recent call will
be scheduled to receive a wakeup.
§Return value
The function returns:
Poll::Pending
if the socket is not available to writePoll::Ready(Ok(n))
n
is the number of bytes sentPoll::Ready(Err(e))
if an error is encountered.
§Errors
This function may encounter any standard I/O error except WouldBlock
.
Sourcepub fn poll_recv(
&self,
cx: &mut Context<'_>,
buf: &mut ReadBuf<'_>,
) -> Poll<Result<()>>
pub fn poll_recv( &self, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>
Attempts to receive a single datagram message on the socket from the remote
address to which it is connect
ed.
The connect
method will connect this socket to a remote address. This method
resolves to an error if the socket is not connected.
Note that on multiple calls to a poll_*
method in the recv
direction, only the
Waker
from the Context
passed to the most recent call will be scheduled to
receive a wakeup.
§Return value
The function returns:
Poll::Pending
if the socket is not ready to readPoll::Ready(Ok(()))
reads dataReadBuf
if the socket is readyPoll::Ready(Err(e))
if an error is encountered.
§Errors
This function may encounter any standard I/O error except WouldBlock
.
Sourcepub fn try_recv_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>
pub fn try_recv_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>
Tries to receive data from the socket without waiting.
§Examples
use tokio::net::UnixDatagram;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let dir = tempfile::tempdir().unwrap();
let client_path = dir.path().join("client.sock");
let server_path = dir.path().join("server.sock");
let socket = UnixDatagram::bind(&client_path)?;
loop {
// Wait for the socket to be readable
socket.readable().await?;
// The buffer is **not** included in the async task and will
// only exist on the stack.
let mut buf = [0; 1024];
// Try to recv data, this may still fail with `WouldBlock`
// if the readiness event is a false positive.
match socket.try_recv_from(&mut buf) {
Ok((n, _addr)) => {
println!("GOT {:?}", &buf[..n]);
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
continue;
}
Err(e) => {
return Err(e);
}
}
}
Ok(())
}
Sourcepub fn try_io<R>(
&self,
interest: Interest,
f: impl FnOnce() -> Result<R>,
) -> Result<R>
pub fn try_io<R>( &self, interest: Interest, f: impl FnOnce() -> Result<R>, ) -> Result<R>
Tries to read or write from the socket using a user-provided IO operation.
If the socket is ready, the provided closure is called. The closure
should attempt to perform IO operation on the socket by manually
calling the appropriate syscall. If the operation fails because the
socket 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 socket 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 socket that failed due to the socket not being
ready. Returning a WouldBlock
error in any other situation will
incorrectly clear the readiness flag, which can cause the socket to
behave incorrectly.
The closure should not perform the IO operation using any of the methods
defined on the Tokio UnixDatagram
type, as this will mess with the
readiness flag and can cause the socket 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.
Sourcepub async fn async_io<R>(
&self,
interest: Interest,
f: impl FnMut() -> Result<R>,
) -> Result<R>
pub async fn async_io<R>( &self, interest: Interest, f: impl FnMut() -> Result<R>, ) -> Result<R>
Reads or writes from the socket using a user-provided IO operation.
The readiness of the socket is awaited and when the socket is ready,
the provided closure is called. The closure should attempt to perform
IO operation on the socket by manually calling the appropriate syscall.
If the operation fails because the socket is not actually ready,
then the closure should return a WouldBlock
error. In such case the
readiness flag is cleared and the socket 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 socket that failed due to the socket not being
ready. Returning a WouldBlock
error in any other situation will
incorrectly clear the readiness flag, which can cause the socket to
behave incorrectly.
The closure should not perform the IO operation using any of the methods
defined on the Tokio UnixDatagram
type, as this will mess with the
readiness flag and can cause the socket 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.
Sourcepub fn local_addr(&self) -> Result<SocketAddr>
pub fn local_addr(&self) -> Result<SocketAddr>
Returns the local address that this socket is bound to.
§Examples
For a socket bound to a local path
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// We use a temporary directory so that the socket
// files left by the bound sockets will get cleaned up.
let tmp = tempdir()?;
// Bind socket to a filesystem path
let socket_path = tmp.path().join("socket");
let socket = UnixDatagram::bind(&socket_path)?;
assert_eq!(socket.local_addr()?.as_pathname().unwrap(), &socket_path);
For an unbound socket
use tokio::net::UnixDatagram;
// Create an unbound socket
let socket = UnixDatagram::unbound()?;
assert!(socket.local_addr()?.is_unnamed());
Sourcepub fn peer_addr(&self) -> Result<SocketAddr>
pub fn peer_addr(&self) -> Result<SocketAddr>
Returns the address of this socket’s peer.
The connect
method will connect the socket to a peer.
§Examples
For a peer with a local path
use tokio::net::UnixDatagram;
use tempfile::tempdir;
// Create an unbound socket
let tx = UnixDatagram::unbound()?;
// Create another, bound socket
let tmp = tempdir()?;
let rx_path = tmp.path().join("rx");
let rx = UnixDatagram::bind(&rx_path)?;
// Connect to the bound socket
tx.connect(&rx_path)?;
assert_eq!(tx.peer_addr()?.as_pathname().unwrap(), &rx_path);
For an unbound peer
use tokio::net::UnixDatagram;
// Create the pair of sockets
let (sock1, sock2) = UnixDatagram::pair()?;
assert!(sock1.peer_addr()?.is_unnamed());
Sourcepub fn take_error(&self) -> Result<Option<Error>>
pub fn take_error(&self) -> Result<Option<Error>>
Returns the value of the SO_ERROR
option.
§Examples
use tokio::net::UnixDatagram;
// Create an unbound socket
let socket = UnixDatagram::unbound()?;
if let Ok(Some(err)) = socket.take_error() {
println!("Got error: {:?}", err);
}
Sourcepub fn shutdown(&self, how: Shutdown) -> Result<()>
pub fn shutdown(&self, how: Shutdown) -> Result<()>
Shuts down the read, write, or both halves of this connection.
This function will cause all pending and future I/O calls on the
specified portions to immediately return with an appropriate value
(see the documentation of Shutdown
).
§Examples
use tokio::net::UnixDatagram;
use std::net::Shutdown;
// Create an unbound socket
let (socket, other) = UnixDatagram::pair()?;
socket.shutdown(Shutdown::Both)?;
// NOTE: the following commented out code does NOT work as expected.
// Due to an underlying issue, the recv call will block indefinitely.
// See: https://github.com/tokio-rs/tokio/issues/1679
//let mut buff = vec![0u8; 24];
//let size = socket.recv(&mut buff).await?;
//assert_eq!(size, 0);
let send_result = socket.send(b"hello world").await;
assert!(send_result.is_err());