pub struct UdpSocket { /* private fields */ }
net
only.Expand description
A UDP socket.
UDP is “connectionless”, unlike TCP. Meaning, regardless of what address you’ve bound to, a UdpSocket
is free to communicate with many different remotes. In tokio there are basically two main ways to use UdpSocket
:
- one to many:
bind
and usesend_to
andrecv_from
to communicate with many different addresses - one to one:
connect
and associate with a single address, usingsend
andrecv
to communicate only with that remote address
This type does not provide a split
method, because this functionality
can be achieved by instead wrapping the socket in an Arc
. Note that
you do not need a Mutex
to share the UdpSocket
— an Arc<UdpSocket>
is enough. This is because all of the methods take &self
instead of
&mut self
. Once you have wrapped it in an Arc
, you can call
.clone()
on the Arc<UdpSocket>
to get multiple shared handles to the
same socket. An example of such usage can be found further down.
§Streams
If you need to listen over UDP and produce a Stream
, you can look
at UdpFramed
.
§Example: one to many (bind)
Using bind
we can create a simple echo server that sends and recv’s with many different clients:
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let sock = UdpSocket::bind("0.0.0.0:8080").await?;
let mut buf = [0; 1024];
loop {
let (len, addr) = sock.recv_from(&mut buf).await?;
println!("{:?} bytes received from {:?}", len, addr);
let len = sock.send_to(&buf[..len], addr).await?;
println!("{:?} bytes sent", len);
}
}
§Example: one to one (connect)
Or using connect
we can echo with a single remote address using send
and recv
:
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let sock = UdpSocket::bind("0.0.0.0:8080").await?;
let remote_addr = "127.0.0.1:59611";
sock.connect(remote_addr).await?;
let mut buf = [0; 1024];
loop {
let len = sock.recv(&mut buf).await?;
println!("{:?} bytes received from {:?}", len, remote_addr);
let len = sock.send(&buf[..len]).await?;
println!("{:?} bytes sent", len);
}
}
§Example: Splitting with Arc
Because send_to
and recv_from
take &self
. It’s perfectly alright
to use an Arc<UdpSocket>
and share the references to multiple tasks.
Here is a similar “echo” example that supports concurrent
sending/receiving:
use tokio::{net::UdpSocket, sync::mpsc};
use std::{io, net::SocketAddr, sync::Arc};
#[tokio::main]
async fn main() -> io::Result<()> {
let sock = UdpSocket::bind("0.0.0.0:8080".parse::<SocketAddr>().unwrap()).await?;
let r = Arc::new(sock);
let s = r.clone();
let (tx, mut rx) = mpsc::channel::<(Vec<u8>, SocketAddr)>(1_000);
tokio::spawn(async move {
while let Some((bytes, addr)) = rx.recv().await {
let len = s.send_to(&bytes, &addr).await.unwrap();
println!("{:?} bytes sent", len);
}
});
let mut buf = [0; 1024];
loop {
let (len, addr) = r.recv_from(&mut buf).await?;
println!("{:?} bytes received from {:?}", len, addr);
tx.send((buf[..len].to_vec(), addr)).await.unwrap();
}
}
Implementations§
Source§impl UdpSocket
impl UdpSocket
Sourcepub async fn bind<A: ToSocketAddrs>(addr: A) -> Result<UdpSocket>
pub async fn bind<A: ToSocketAddrs>(addr: A) -> Result<UdpSocket>
This function will create a new UDP socket and attempt to bind it to
the addr
provided.
Binding with a port number of 0 will request that the OS assigns a port
to this listener. The port allocated can be queried via the local_addr
method.
§Example
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let sock = UdpSocket::bind("0.0.0.0:8080").await?;
// use `sock`
Ok(())
}
Sourcepub fn from_std(socket: UdpSocket) -> Result<UdpSocket>
pub fn from_std(socket: UdpSocket) -> Result<UdpSocket>
Creates new UdpSocket
from a previously bound std::net::UdpSocket
.
This function is intended to be used to wrap a UDP socket from the standard library in the Tokio equivalent.
This can be used in conjunction with socket2
’s Socket
interface to
configure a socket before it’s handed off, such as setting options like
reuse_address
or binding to multiple addresses.
§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 thread-local runtime is not set.
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.
§Example
use tokio::net::UdpSocket;
let addr = "0.0.0.0:8080".parse::<SocketAddr>().unwrap();
let std_sock = std::net::UdpSocket::bind(addr)?;
std_sock.set_nonblocking(true)?;
let sock = UdpSocket::from_std(std_sock)?;
// use `sock`
Sourcepub fn into_std(self) -> Result<UdpSocket>
pub fn into_std(self) -> Result<UdpSocket>
Turns a tokio::net::UdpSocket
into a std::net::UdpSocket
.
The returned std::net::UdpSocket
will have nonblocking mode set as
true
. Use set_nonblocking
to change the blocking mode if needed.
§Examples
use std::error::Error;
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
let tokio_socket = tokio::net::UdpSocket::bind("127.0.0.1:0").await?;
let std_socket = tokio_socket.into_std()?;
std_socket.set_nonblocking(false)?;
Ok(())
}
Sourcepub fn local_addr(&self) -> Result<SocketAddr>
pub fn local_addr(&self) -> Result<SocketAddr>
Returns the local address that this socket is bound to.
§Example
use tokio::net::UdpSocket;
let addr = "0.0.0.0:8080".parse::<SocketAddr>().unwrap();
let sock = UdpSocket::bind(addr).await?;
// the address the socket is bound to
let local_addr = sock.local_addr()?;
Sourcepub fn peer_addr(&self) -> Result<SocketAddr>
pub fn peer_addr(&self) -> Result<SocketAddr>
Returns the socket address of the remote peer this socket was connected to.
§Example
use tokio::net::UdpSocket;
let addr = "0.0.0.0:8080".parse::<SocketAddr>().unwrap();
let peer = "127.0.0.1:11100".parse::<SocketAddr>().unwrap();
let sock = UdpSocket::bind(addr).await?;
sock.connect(peer).await?;
assert_eq!(peer, sock.peer_addr()?);
Sourcepub async fn connect<A: ToSocketAddrs>(&self, addr: A) -> Result<()>
pub async fn connect<A: ToSocketAddrs>(&self, addr: A) -> Result<()>
Connects the UDP socket setting the default destination for send() and
limiting packets that are read via recv
from the address specified in
addr
.
§Example
use tokio::net::UdpSocket;
let sock = UdpSocket::bind("0.0.0.0:8080".parse::<SocketAddr>().unwrap()).await?;
let remote_addr = "127.0.0.1:59600".parse::<SocketAddr>().unwrap();
sock.connect(remote_addr).await?;
let mut buf = [0u8; 32];
// recv from remote_addr
let len = sock.recv(&mut buf).await?;
// send to remote_addr
let _len = sock.send(&buf[..len]).await?;
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::{self, Interest};
use tokio::net::UdpSocket;
#[tokio::main]
async fn main() -> io::Result<()> {
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
loop {
let ready = socket.ready(Interest::READABLE | Interest::WRITABLE).await?;
if ready.is_readable() {
// The buffer is **not** included in the async task and will only exist
// on the stack.
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::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Bind socket
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
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 udp stream is not currently ready for sending, this method will
store a clone of the Waker
from the provided Context
. When the udp
stream 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 udp stream is not ready for writing.Poll::Ready(Ok(()))
if the udp stream 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 send(&self, buf: &[u8]) -> Result<usize>
pub async fn send(&self, buf: &[u8]) -> Result<usize>
Sends data on the socket to the remote address that the socket is connected to.
The connect
method will connect this socket to a remote address.
This method will fail if the socket is not connected.
§Return
On success, the number of bytes sent is returned, otherwise, the encountered error is returned.
§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::io;
use tokio::net::UdpSocket;
#[tokio::main]
async fn main() -> io::Result<()> {
// Bind socket
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
// Send a message
socket.send(b"hello world").await?;
Ok(())
}
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 try_send(&self, buf: &[u8]) -> Result<usize>
pub fn try_send(&self, buf: &[u8]) -> Result<usize>
Tries to send data on the socket to the remote address to which it is connected.
When the socket buffer is full, Err(io::ErrorKind::WouldBlock)
is
returned. This function is usually paired with writable()
.
§Returns
If successful, Ok(n)
is returned, where n
is the number of bytes
sent. If the socket is not ready to send data,
Err(ErrorKind::WouldBlock)
is returned.
§Examples
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Bind a UDP socket
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
// Connect to a peer
socket.connect("127.0.0.1:8081").await?;
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 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::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
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 udp stream is not currently ready for receiving, this method will
store a clone of the Waker
from the provided Context
. When the udp
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 udp stream is not ready for reading.Poll::Ready(Ok(()))
if the udp stream 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 async fn recv(&self, buf: &mut [u8]) -> Result<usize>
pub async fn recv(&self, buf: &mut [u8]) -> Result<usize>
Receives a single datagram message on the socket from the remote address to which it is connected. On success, returns the number of bytes read.
The function must be called with valid byte array buf
of sufficient
size to hold the message bytes. If a message is too long to fit in the
supplied buffer, excess bytes may be discarded.
The connect
method will connect this socket to a remote address.
This method will fail if the socket is not connected.
§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.
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Bind socket
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
let mut buf = vec![0; 10];
let n = socket.recv(&mut buf).await?;
println!("received {} bytes {:?}", n, &buf[..n]);
Ok(())
}
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(&self, buf: &mut [u8]) -> Result<usize>
pub fn try_recv(&self, buf: &mut [u8]) -> Result<usize>
Tries to receive a single datagram message on the socket from the remote address to which it is connected. On success, returns the number of bytes read.
This method must be called with valid byte array buf
of sufficient size
to hold the message bytes. If a message is too long to fit in the
supplied buffer, excess bytes may be discarded.
When there is no pending data, Err(io::ErrorKind::WouldBlock)
is
returned. This function is usually paired with readable()
.
§Examples
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
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<B: BufMut>(&self, buf: &mut B) -> Result<usize>
Available on crate feature io-util
only.
pub fn try_recv_buf<B: BufMut>(&self, buf: &mut B) -> Result<usize>
io-util
only.Tries to receive data from the stream into the provided buffer, advancing the buffer’s internal cursor, returning how many bytes were read.
This method must be called with valid byte array buf
of sufficient size
to hold the message bytes. If a message is too long to fit in the
supplied buffer, excess bytes may be discarded.
This method can be used even if buf
is uninitialized.
When there is no pending data, Err(io::ErrorKind::WouldBlock)
is
returned. This function is usually paired with readable()
.
§Examples
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
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>
Available on crate feature io-util
only.
pub async fn recv_buf<B: BufMut>(&self, buf: &mut B) -> Result<usize>
io-util
only.Receives a single datagram message on the socket from the remote address to which it is connected, advancing the buffer’s internal cursor, returning how many bytes were read.
This method must be called with valid byte array buf
of sufficient size
to hold the message bytes. If a message is too long to fit in the
supplied buffer, excess bytes may be discarded.
This method can be used even if buf
is uninitialized.
§Examples
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
let mut buf = Vec::with_capacity(512);
let len = socket.recv_buf(&mut buf).await?;
println!("received {} bytes {:?}", len, &buf[..len]);
Ok(())
}
Sourcepub fn try_recv_buf_from<B: BufMut>(
&self,
buf: &mut B,
) -> Result<(usize, SocketAddr)>
Available on crate feature io-util
only.
pub fn try_recv_buf_from<B: BufMut>( &self, buf: &mut B, ) -> Result<(usize, SocketAddr)>
io-util
only.Tries to receive a single datagram message on the socket. On success, returns the number of bytes read and the origin.
This method must be called with valid byte array buf
of sufficient size
to hold the message bytes. If a message is too long to fit in the
supplied buffer, excess bytes may be discarded.
This method can be used even if buf
is uninitialized.
When there is no pending data, Err(io::ErrorKind::WouldBlock)
is
returned. This function is usually paired with readable()
.
§Notes
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
§Examples
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
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)>
Available on crate feature io-util
only.
pub async fn recv_buf_from<B: BufMut>( &self, buf: &mut B, ) -> Result<(usize, SocketAddr)>
io-util
only.Receives a single datagram message on the socket, advancing the buffer’s internal cursor, returning how many bytes were read and the origin.
This method must be called with valid byte array buf
of sufficient size
to hold the message bytes. If a message is too long to fit in the
supplied buffer, excess bytes may be discarded.
This method can be used even if buf
is uninitialized.
§Notes
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
§Examples
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
socket.connect("127.0.0.1:8081").await?;
let mut buf = Vec::with_capacity(512);
let (len, addr) = socket.recv_buf_from(&mut buf).await?;
println!("received {:?} bytes from {:?}", len, addr);
Ok(())
}
Sourcepub async fn send_to<A: ToSocketAddrs>(
&self,
buf: &[u8],
target: A,
) -> Result<usize>
pub async fn send_to<A: ToSocketAddrs>( &self, buf: &[u8], target: A, ) -> Result<usize>
Sends data on the socket to the given address. On success, returns the number of bytes written.
Address type can be any implementor of ToSocketAddrs
trait. See its
documentation for concrete examples.
It is possible for addr
to yield multiple addresses, but send_to
will only send data to the first address yielded by addr
.
This will return an error when the IP version of the local socket does
not match that returned from ToSocketAddrs
.
§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.
§Example
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
let len = socket.send_to(b"hello world", "127.0.0.1:8081").await?;
println!("Sent {} bytes", len);
Ok(())
}
Sourcepub fn poll_send_to(
&self,
cx: &mut Context<'_>,
buf: &[u8],
target: SocketAddr,
) -> Poll<Result<usize>>
pub fn poll_send_to( &self, cx: &mut Context<'_>, buf: &[u8], target: SocketAddr, ) -> Poll<Result<usize>>
Attempts to send data on the socket to a given 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 try_send_to(&self, buf: &[u8], target: SocketAddr) -> Result<usize>
pub fn try_send_to(&self, buf: &[u8], target: SocketAddr) -> Result<usize>
Tries to send data on the socket to the given address, but if the send is blocked this will return right away.
This function is usually paired with writable()
.
§Returns
If successful, returns the number of bytes sent
Users should ensure that when the remote cannot receive, the
ErrorKind::WouldBlock
is properly handled. An error can also occur
if the IP version of the socket does not match that of target
.
§Example
use tokio::net::UdpSocket;
use std::error::Error;
use std::io;
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
let dst = "127.0.0.1:8081".parse()?;
loop {
socket.writable().await?;
match socket.try_send_to(&b"hello world"[..], dst) {
Ok(sent) => {
println!("sent {} bytes", sent);
break;
}
Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
// Writable false positive.
continue;
}
Err(e) => return Err(e.into()),
}
}
Ok(())
}
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 a single datagram message on the socket. On success, returns the number of bytes read and the origin.
The function must be called with valid byte array buf
of sufficient
size to hold the message bytes. If a message is too long to fit in the
supplied buffer, excess bytes may be discarded.
§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.
§Example
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
let mut buf = vec![0u8; 32];
let (len, addr) = socket.recv_from(&mut buf).await?;
println!("received {:?} bytes from {:?}", len, addr);
Ok(())
}
§Notes
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
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 socket.
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
.
§Notes
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
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 a single datagram message on the socket. On success, returns the number of bytes read and the origin.
This method must be called with valid byte array buf
of sufficient size
to hold the message bytes. If a message is too long to fit in the
supplied buffer, excess bytes may be discarded.
When there is no pending data, Err(io::ErrorKind::WouldBlock)
is
returned. This function is usually paired with readable()
.
§Notes
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
§Examples
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Connect to a peer
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
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 UdpSocket
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 UdpSocket
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 async fn peek_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>
pub async fn peek_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>
Receives data from the socket, without removing it from the input queue. On success, returns the number of bytes read and the address from whence the data came.
§Notes
On Windows, if the data is larger than the buffer specified, the buffer
is filled with the first part of the data, and peek_from
returns the error
WSAEMSGSIZE(10040)
. The excess data is lost.
Make sure to always use a sufficiently large buffer to hold the
maximum UDP packet size, which can be up to 65536 bytes in size.
MacOS will return an error if you pass a zero-sized buffer.
If you’re merely interested in learning the sender of the data at the head of the queue,
try peek_sender
.
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
§Examples
use tokio::net::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let socket = UdpSocket::bind("127.0.0.1:8080").await?;
let mut buf = vec![0u8; 32];
let (len, addr) = socket.peek_from(&mut buf).await?;
println!("peeked {:?} bytes from {:?}", len, addr);
Ok(())
}
Sourcepub fn poll_peek_from(
&self,
cx: &mut Context<'_>,
buf: &mut ReadBuf<'_>,
) -> Poll<Result<SocketAddr>>
pub fn poll_peek_from( &self, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<SocketAddr>>
Receives data from the socket, without removing it from the input queue. On success, returns the sending address of the datagram.
§Notes
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
On Windows, if the data is larger than the buffer specified, the buffer
is filled with the first part of the data, and peek returns the error
WSAEMSGSIZE(10040)
. The excess data is lost.
Make sure to always use a sufficiently large buffer to hold the
maximum UDP packet size, which can be up to 65536 bytes in size.
MacOS will return an error if you pass a zero-sized buffer.
If you’re merely interested in learning the sender of the data at the head of the queue,
try poll_peek_sender
.
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
§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 try_peek_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>
pub fn try_peek_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>
Tries to receive data on the socket without removing it from the input queue. On success, returns the number of bytes read and the sending address of the datagram.
When there is no pending data, Err(io::ErrorKind::WouldBlock)
is
returned. This function is usually paired with readable()
.
§Notes
On Windows, if the data is larger than the buffer specified, the buffer
is filled with the first part of the data, and peek returns the error
WSAEMSGSIZE(10040)
. The excess data is lost.
Make sure to always use a sufficiently large buffer to hold the
maximum UDP packet size, which can be up to 65536 bytes in size.
MacOS will return an error if you pass a zero-sized buffer.
If you’re merely interested in learning the sender of the data at the head of the queue,
try try_peek_sender
.
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
Sourcepub async fn peek_sender(&self) -> Result<SocketAddr>
pub async fn peek_sender(&self) -> Result<SocketAddr>
Retrieve the sender of the data at the head of the input queue, waiting if empty.
This is equivalent to calling peek_from
with a zero-sized buffer,
but suppresses the WSAEMSGSIZE
error on Windows and the “invalid argument” error on macOS.
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
Sourcepub fn poll_peek_sender(&self, cx: &mut Context<'_>) -> Poll<Result<SocketAddr>>
pub fn poll_peek_sender(&self, cx: &mut Context<'_>) -> Poll<Result<SocketAddr>>
Retrieve the sender of the data at the head of the input queue, scheduling a wakeup if empty.
This is equivalent to calling poll_peek_from
with a zero-sized buffer,
but suppresses the WSAEMSGSIZE
error on Windows and the “invalid argument” error on macOS.
§Notes
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.
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
Sourcepub fn try_peek_sender(&self) -> Result<SocketAddr>
pub fn try_peek_sender(&self) -> Result<SocketAddr>
Try to retrieve the sender of the data at the head of the input queue.
When there is no pending data, Err(io::ErrorKind::WouldBlock)
is
returned. This function is usually paired with readable()
.
Note that the socket address cannot be implicitly trusted, because it is relatively trivial to send a UDP datagram with a spoofed origin in a packet injection attack. Because UDP is stateless and does not validate the origin of a packet, the attacker does not need to be able to intercept traffic in order to interfere. It is important to be aware of this when designing your application-level protocol.
Sourcepub fn broadcast(&self) -> Result<bool>
pub fn broadcast(&self) -> Result<bool>
Gets the value of the SO_BROADCAST
option for this socket.
For more information about this option, see set_broadcast
.
Sourcepub fn set_broadcast(&self, on: bool) -> Result<()>
pub fn set_broadcast(&self, on: bool) -> Result<()>
Sets the value of the SO_BROADCAST
option for this socket.
When enabled, this socket is allowed to send packets to a broadcast address.
Sourcepub fn multicast_loop_v4(&self) -> Result<bool>
pub fn multicast_loop_v4(&self) -> Result<bool>
Gets the value of the IP_MULTICAST_LOOP
option for this socket.
For more information about this option, see set_multicast_loop_v4
.
Sourcepub fn set_multicast_loop_v4(&self, on: bool) -> Result<()>
pub fn set_multicast_loop_v4(&self, on: bool) -> Result<()>
Sets the value of the IP_MULTICAST_LOOP
option for this socket.
If enabled, multicast packets will be looped back to the local socket.
§Note
This may not have any affect on IPv6 sockets.
Sourcepub fn multicast_ttl_v4(&self) -> Result<u32>
pub fn multicast_ttl_v4(&self) -> Result<u32>
Gets the value of the IP_MULTICAST_TTL
option for this socket.
For more information about this option, see set_multicast_ttl_v4
.
Sourcepub fn set_multicast_ttl_v4(&self, ttl: u32) -> Result<()>
pub fn set_multicast_ttl_v4(&self, ttl: u32) -> Result<()>
Sets the value of the IP_MULTICAST_TTL
option for this socket.
Indicates the time-to-live value of outgoing multicast packets for this socket. The default value is 1 which means that multicast packets don’t leave the local network unless explicitly requested.
§Note
This may not have any affect on IPv6 sockets.
Sourcepub fn multicast_loop_v6(&self) -> Result<bool>
pub fn multicast_loop_v6(&self) -> Result<bool>
Gets the value of the IPV6_MULTICAST_LOOP
option for this socket.
For more information about this option, see set_multicast_loop_v6
.
Sourcepub fn set_multicast_loop_v6(&self, on: bool) -> Result<()>
pub fn set_multicast_loop_v6(&self, on: bool) -> Result<()>
Sets the value of the IPV6_MULTICAST_LOOP
option for this socket.
Controls whether this socket sees the multicast packets it sends itself.
§Note
This may not have any affect on IPv4 sockets.
Sourcepub fn set_ttl(&self, ttl: u32) -> Result<()>
pub fn set_ttl(&self, ttl: u32) -> Result<()>
Sets the value for the IP_TTL
option on this socket.
This value sets the time-to-live field that is used in every packet sent from this socket.
§Examples
use tokio::net::UdpSocket;
let sock = UdpSocket::bind("127.0.0.1:8080").await?;
sock.set_ttl(60)?;
Sourcepub fn tos(&self) -> Result<u32>
Available on neither Fuchsia nor Redox nor Solaris nor illumos.
pub fn tos(&self) -> Result<u32>
Gets the value of the IP_TOS
option for this socket.
For more information about this option, see set_tos
.
NOTE: On Windows, IP_TOS
is only supported on Windows 8+ or
Windows Server 2012+.
Sourcepub fn set_tos(&self, tos: u32) -> Result<()>
Available on neither Fuchsia nor Redox nor Solaris nor illumos.
pub fn set_tos(&self, tos: u32) -> Result<()>
Sets the value for the IP_TOS
option on this socket.
This value sets the type-of-service field that is used in every packet sent from this socket.
NOTE: On Windows, IP_TOS
is only supported on Windows 8+ or
Windows Server 2012+.
Sourcepub fn device(&self) -> Result<Option<Vec<u8>>>
Available on Android or Fuchsia or Linux only.
pub fn device(&self) -> Result<Option<Vec<u8>>>
Gets the value for the SO_BINDTODEVICE
option on this socket
This value gets the socket-bound device’s interface name.
Sourcepub fn bind_device(&self, interface: Option<&[u8]>) -> Result<()>
Available on Android or Fuchsia or Linux only.
pub fn bind_device(&self, interface: Option<&[u8]>) -> Result<()>
Sets the value for the SO_BINDTODEVICE
option on this socket
If a socket is bound to an interface, only packets received from that
particular interface are processed by the socket. Note that this only
works for some socket types, particularly AF_INET
sockets.
If interface
is None
or an empty string it removes the binding.
Sourcepub fn join_multicast_v4(
&self,
multiaddr: Ipv4Addr,
interface: Ipv4Addr,
) -> Result<()>
pub fn join_multicast_v4( &self, multiaddr: Ipv4Addr, interface: Ipv4Addr, ) -> Result<()>
Executes an operation of the IP_ADD_MEMBERSHIP
type.
This function specifies a new multicast group for this socket to join.
The address must be a valid multicast address, and interface
is the
address of the local interface with which the system should join the
multicast group. If it’s equal to INADDR_ANY
then an appropriate
interface is chosen by the system.
Sourcepub fn join_multicast_v6(
&self,
multiaddr: &Ipv6Addr,
interface: u32,
) -> Result<()>
pub fn join_multicast_v6( &self, multiaddr: &Ipv6Addr, interface: u32, ) -> Result<()>
Executes an operation of the IPV6_ADD_MEMBERSHIP
type.
This function specifies a new multicast group for this socket to join.
The address must be a valid multicast address, and interface
is the
index of the interface to join/leave (or 0 to indicate any interface).
Sourcepub fn leave_multicast_v4(
&self,
multiaddr: Ipv4Addr,
interface: Ipv4Addr,
) -> Result<()>
pub fn leave_multicast_v4( &self, multiaddr: Ipv4Addr, interface: Ipv4Addr, ) -> Result<()>
Executes an operation of the IP_DROP_MEMBERSHIP
type.
For more information about this option, see join_multicast_v4
.
Sourcepub fn leave_multicast_v6(
&self,
multiaddr: &Ipv6Addr,
interface: u32,
) -> Result<()>
pub fn leave_multicast_v6( &self, multiaddr: &Ipv6Addr, interface: u32, ) -> Result<()>
Executes an operation of the IPV6_DROP_MEMBERSHIP
type.
For more information about this option, see join_multicast_v6
.
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::UdpSocket;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
// Create a socket
let socket = UdpSocket::bind("0.0.0.0:8080").await?;
if let Ok(Some(err)) = socket.take_error() {
println!("Got error: {:?}", err);
}
Ok(())
}