Struct tokio::net::UdpSocket

pub struct UdpSocket { /* fields omitted */ }

This is supported on crate feature net only.

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 use send_to and [recv_from](UdpSocket::recv_from) to communicate with many different addresses - one to one: [connect](UdpSocket::connect) and associate with a single address, using [send](UdpSocket::send) and recv to communicate only with that remote address

UdpSocket can also be used concurrently to send_to and recv_from in different tasks, all that's required is that you Arc<UdpSocket> and clone a reference for each task.

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: Sending/Receiving concurrently

Because send_to and recv_from take &self. It's perfectly alright to Arc<UdpSocket> and share the references to multiple tasks, in order to send/receive concurrently. Here is a similar "echo" example but 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

impl UdpSocket

pub async fn bind<A: ToSocketAddrs>(addr: A) -> Result<UdpSocket>

This is supported on crate feature net only.

This function will create a new UDP socket and attempt to bind it to the addr provided.

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

pub fn from_std(socket: UdpSocket) -> Result<UdpSocket>

This is supported on crate feature net only.

Creates a new UdpSocket from the previously bound socket provided.

The socket given will be registered with the event loop that handle is associated with. This function requires that socket has previously been bound to an address to work correctly.

This can be used in conjunction with net2's UdpBuilder interface to configure a socket before it's handed off, such as setting options like reuse_address or binding to multiple addresses.

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)?;
let sock = UdpSocket::from_std(std_sock)?;
// use `sock`

pub fn local_addr(&self) -> Result<SocketAddr>

This is supported on crate feature net only.

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

pub async fn connect<A: ToSocketAddrs, '_>(&'_ self, addr: A) -> Result<()>

This is supported on crate feature net only.

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

pub async fn send<'_, '_>(&'_ self, buf: &'_ [u8]) -> Result<usize>

This is supported on crate feature net only.

Returns a future that sends data on the socket to the remote address to which it is connected. On success, the future will resolve to the number of bytes written.

The connect method will connect this socket to a remote address. The future will resolve to an error if the socket is not connected.

pub fn try_send(&self, buf: &[u8]) -> Result<usize>

This is supported on crate feature net only.

Try to send data on the socket to the remote address to which it is connected.

Returns

If successfull, the number of bytes sent is returned. Users should ensure that when the remote cannot receive, the ErrorKind::WouldBlock is properly handled.

pub async fn recv<'_, '_>(&'_ self, buf: &'_ mut [u8]) -> Result<usize>

This is supported on crate feature net only.

Returns a future that receives a single datagram message on the socket from the remote address to which it is connected. On success, the future will resolve to 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. The future will fail if the socket is not connected.

pub async fn send_to<A: ToSocketAddrs, '_, '_>(
    &'_ self,
    buf: &'_ [u8],
    target: A
) -> Result<usize>

This is supported on crate feature net only.

Returns a future that sends data on the socket to the given address. On success, the future will resolve to the number of bytes written.

The future will resolve to an error if the IP version of the socket does not match that of target.

Example

use tokio::net::UdpSocket;

let sock = UdpSocket::bind("0.0.0.0:8080".parse::<SocketAddr>().unwrap()).await?;
let buf = b"hello world";
let remote_addr = "127.0.0.1:58000".parse::<SocketAddr>().unwrap();
let _len = sock.send_to(&buf[..], remote_addr).await?;

pub fn try_send_to(&self, buf: &[u8], target: SocketAddr) -> Result<usize>

This is supported on crate feature net only.

Try to send data on the socket to the given address, but if the send is blocked this will return right away.

Returns

If successfull, 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;

let sock = UdpSocket::bind("0.0.0.0:8080".parse::<SocketAddr>().unwrap()).await?;
let buf = b"hello world";
let remote_addr = "127.0.0.1:58000".parse::<SocketAddr>().unwrap();
let _len = sock.try_send_to(&buf[..], remote_addr)?;

pub async fn recv_from<'_, '_>(
    &'_ self,
    buf: &'_ mut [u8]
) -> Result<(usize, SocketAddr)>

This is supported on crate feature net only.

Returns a future that receives a single datagram on the socket. On success, the future resolves to 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.

Example

use tokio::net::UdpSocket;

let sock = UdpSocket::bind("0.0.0.0:8080".parse::<SocketAddr>().unwrap()).await?;
let mut buf = [0u8; 32];
let (len, addr) = sock.recv_from(&mut buf).await?;
println!("received {:?} bytes from {:?}", len, addr);

pub fn broadcast(&self) -> Result<bool>

This is supported on crate feature net only.

Gets the value of the SO_BROADCAST option for this socket.

For more information about this option, see set_broadcast.

pub fn set_broadcast(&self, on: bool) -> Result<()>

This is supported on crate feature net only.

Sets the value of the SO_BROADCAST option for this socket.

When enabled, this socket is allowed to send packets to a broadcast address.

pub fn multicast_loop_v4(&self) -> Result<bool>

This is supported on crate feature net only.

Gets the value of the IP_MULTICAST_LOOP option for this socket.

For more information about this option, see set_multicast_loop_v4.

pub fn set_multicast_loop_v4(&self, on: bool) -> Result<()>

This is supported on crate feature net only.

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.

pub fn multicast_ttl_v4(&self) -> Result<u32>

This is supported on crate feature net only.

Gets the value of the IP_MULTICAST_TTL option for this socket.

For more information about this option, see set_multicast_ttl_v4.

pub fn set_multicast_ttl_v4(&self, ttl: u32) -> Result<()>

This is supported on crate feature net only.

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.

pub fn multicast_loop_v6(&self) -> Result<bool>

This is supported on crate feature net only.

Gets the value of the IPV6_MULTICAST_LOOP option for this socket.

For more information about this option, see set_multicast_loop_v6.

pub fn set_multicast_loop_v6(&self, on: bool) -> Result<()>

This is supported on crate feature net only.

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.

pub fn ttl(&self) -> Result<u32>

This is supported on crate feature net only.

Gets the value of the IP_TTL option for this socket.

For more information about this option, see set_ttl.

Examples

use tokio::net::UdpSocket;

let sock = UdpSocket::bind("127.0.0.1:8080").await?;

println!("{:?}", sock.ttl()?);

pub fn set_ttl(&self, ttl: u32) -> Result<()>

This is supported on crate feature net only.

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)?;

pub fn join_multicast_v4(
    &self,
    multiaddr: Ipv4Addr,
    interface: Ipv4Addr
) -> Result<()>

This is supported on crate feature net only.

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.

pub fn join_multicast_v6(
    &self,
    multiaddr: &Ipv6Addr,
    interface: u32
) -> Result<()>

This is supported on crate feature net only.

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

pub fn leave_multicast_v4(
    &self,
    multiaddr: Ipv4Addr,
    interface: Ipv4Addr
) -> Result<()>

This is supported on crate feature net only.

Executes an operation of the IP_DROP_MEMBERSHIP type.

For more information about this option, see join_multicast_v4.

pub fn leave_multicast_v6(
    &self,
    multiaddr: &Ipv6Addr,
    interface: u32
) -> Result<()>

This is supported on crate feature net only.

Executes an operation of the IPV6_DROP_MEMBERSHIP type.

For more information about this option, see join_multicast_v6.

Trait Implementations

impl AsRawFd for UdpSocket

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for UdpSocket

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

Formats the value using the given formatter.

impl TryFrom<UdpSocket> for UdpSocket

type Error = Error

The type returned in the event of a conversion error.

fn try_from(stream: UdpSocket) -> Result<Self, Self::Error>

Consumes stream, returning the tokio I/O object.

This is equivalent to UdpSocket::from_std(stream).