Struct UdpSocket

pub struct UdpSocket { /* private fields */ }

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 to communicate with many different addresses
• one to one: connect and associate with a single address, using send and recv 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

TODO: document

Implementations

impl UdpSocket

pub async fn bind<A>(addr: A) -> Result<UdpSocket, Box<dyn Error + Sync + Send>>

where A: TryInto<SocketAddress>, <A as TryInto<SocketAddress>>::Error: Into<Box<dyn Error + Sync + Send>>,

Creates a new UdpSocket, which will be bound to the specified address.

The returned socket is ready for accepting connections and connecting to others.

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.

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

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 rama_net::socket::Socket 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 rama_udp::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 into_std(self) -> Result<UdpSocket, Error>

Turns a 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 rama_core::error::BoxError;
use rama_net::address::SocketAddress;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    let socket = rama_udp::UdpSocket::bind(SocketAddress::local_ipv4(0)).await?;
    let std_socket = socket.into_std()?;
    std_socket.set_nonblocking(false)?;
    Ok(())
}

pub fn as_socket(&self) -> SockRef<'_>

Expose a reference to self as a rama_net::socket::SockRef.

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

Returns the local address that this socket is bound to.

Example

use rama_udp::UdpSocket;
use rama_core::error::BoxError;
use rama_net::address::SocketAddress;

let addr = SocketAddress::local_ipv4(8080);
let sock = UdpSocket::bind(addr).await?;
// the address the socket is bound to
let local_addr = sock.local_addr()?;

pub fn peer_addr(&self) -> Result<SocketAddr, Error>

Returns the socket address of the remote peer this socket was connected to.

Example

use rama_udp::UdpSocket;
use rama_core::error::BoxError;
use rama_net::address::SocketAddress;

let addr = SocketAddress::local_ipv4(8080);
let peer = SocketAddress::local_ipv4(11100);
let sock = UdpSocket::bind(addr).await?;
sock.connect(peer).await?;
assert_eq!(peer, sock.peer_addr()?.into());

pub async fn connect<A>( &self, addr: A, ) -> Result<(), Box<dyn Error + Sync + Send>>

where A: TryInto<SocketAddress>, <A as TryInto<SocketAddress>>::Error: Into<Box<dyn Error + Sync + Send>>,

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 rama_udp::UdpSocket;
use rama_core::error::BoxError;
use rama_net::address::SocketAddress;

let sock = UdpSocket::bind(SocketAddress::default_ipv4(8080)).await?;

let remote_addr = SocketAddress::local_ipv4(59600);
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, Error>

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 rama_core::error::BoxError;
use rama_udp::UdpSocket;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    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(())
}

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

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 rama_udp::UdpSocket;
use rama_core::error::BoxError;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    // 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(())
}

pub async fn recv_buf<B>(&self, buf: &mut B) -> Result<usize, Error>

where B: BufMut,

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 rama_udp::UdpSocket;
use rama_core::error::BoxError;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    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(())
}

pub async fn recv_buf_from<B>( &self, buf: &mut B, ) -> Result<(usize, SocketAddress), Error>

where B: BufMut,

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 rama_udp::UdpSocket;
use rama_core::error::BoxError;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    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(())
}

pub async fn send_to<A>( &self, buf: &[u8], addr: A, ) -> Result<usize, Box<dyn Error + Sync + Send>>

where A: TryInto<SocketAddress>, <A as TryInto<SocketAddress>>::Error: Into<Box<dyn Error + Sync + Send>>,

Sends data on the socket to the given address. On success, returns the number of bytes written.

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 rama_udp::UdpSocket;
use rama_core::error::BoxError;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    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(())
}

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

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 rama_udp::UdpSocket;
use rama_core::error::BoxError;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    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.

pub async fn peek(&self, buf: &mut [u8]) -> Result<usize, Error>

Receives a single datagram from the connected address without removing it from the queue. On success, returns the number of bytes read 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 rama_udp::UdpSocket;
use rama_core::error::BoxError;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;

    let mut buf = vec![0u8; 32];
    let len = socket.peek(&mut buf).await?;

    println!("peeked {:?} bytes", len);

    Ok(())
}

pub async fn peek_from( &self, buf: &mut [u8], ) -> Result<(usize, SocketAddress), Error>

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 rama_udp::UdpSocket;
use rama_core::error::BoxError;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    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(())
}

pub async fn peek_sender(&self) -> Result<SocketAddress, Error>

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.

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

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<(), Error>

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, Error>

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<(), Error>

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, Error>

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<(), Error>

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, Error>

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<(), Error>

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, Error>

Gets the value of the IP_TTL option for this socket.

For more information about this option, see set_ttl.

Examples

use rama_udp::UdpSocket;
use rama_core::error::BoxError;

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

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

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

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 rama_udp::UdpSocket;
use rama_core::error::BoxError;

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<(), Error>

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<(), Error>

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<(), Error>

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<(), Error>

Executes an operation of the IPV6_DROP_MEMBERSHIP type.

For more information about this option, see join_multicast_v6.

pub fn take_error(&self) -> Result<Option<Error>, Error>

Returns the value of the SO_ERROR option.

Examples

use rama_udp::UdpSocket;
use rama_core::error::BoxError;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    let socket = UdpSocket::bind("0.0.0.0:8080").await?;

    if let Ok(Some(err)) = socket.take_error() {
        println!("Got error: {:?}", err);
    }

    Ok(())
}

pub fn into_framed<C>(self, codec: C) -> UdpFramed<C>

Consume this UdpSocket into a UdpFramed using the given C codec.

Trait Implementations

impl AsFd for UdpSocket

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl AsRawFd for UdpSocket

fn as_raw_fd(&self) -> i32

Extracts the raw file descriptor.

impl Debug for UdpSocket

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

Formats the value using the given formatter.

impl From<UdpSocket> for UdpSocket

fn from(value: UdpSocket) -> UdpSocket

Converts to this type from the input type.

impl TryFrom<Socket> for UdpSocket

type Error = Error

The type returned in the event of a conversion error.

fn try_from( value: Socket, ) -> Result<UdpSocket, <UdpSocket as TryFrom<Socket>>::Error>

Performs the conversion.

impl TryFrom<UdpSocket> for UdpSocket

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

Consumes stream, returning the tokio I/O object.

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

type Error = Error

The type returned in the event of a conversion error.