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

Examples

Bind and connect a pair of sockets and send a packet:

use std::net::SocketAddr;

use compio_net::UdpSocket;

let first_addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
let second_addr: SocketAddr = "127.0.0.1:0".parse().unwrap();

// bind sockets
let mut socket = UdpSocket::bind(first_addr).await.unwrap();
let first_addr = socket.local_addr().unwrap();
let mut other_socket = UdpSocket::bind(second_addr).await.unwrap();
let second_addr = other_socket.local_addr().unwrap();

// connect sockets
socket.connect(second_addr).await.unwrap();
other_socket.connect(first_addr).await.unwrap();

let buf = Vec::with_capacity(12);

// write data
socket.send("Hello world!").await.unwrap();

// read data
let (n_bytes, buf) = other_socket.recv(buf).await.unwrap();

assert_eq!(n_bytes, buf.len());
assert_eq!(buf, b"Hello world!");

Send and receive packets without connecting:

use std::net::SocketAddr;

use compio_net::UdpSocket;
use socket2::SockAddr;

let first_addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
let second_addr: SocketAddr = "127.0.0.1:0".parse().unwrap();

// bind sockets
let mut socket = UdpSocket::bind(first_addr).await.unwrap();
let first_addr = socket.local_addr().unwrap();
let mut other_socket = UdpSocket::bind(second_addr).await.unwrap();
let second_addr = other_socket.local_addr().unwrap();

let buf = Vec::with_capacity(32);

// write data
socket.send_to("hello world", second_addr).await.unwrap();

// read data
let ((n_bytes, addr), buf) = other_socket.recv_from(buf).await.unwrap();

assert_eq!(addr, first_addr);
assert_eq!(n_bytes, buf.len());
assert_eq!(buf, b"hello world");

Implementations

impl UdpSocket

pub async fn bind(addr: impl ToSocketAddrsAsync) -> Result<Self>

Creates a new UDP socket and attempt to bind it to the addr provided.

pub async fn connect(&self, addr: impl ToSocketAddrsAsync) -> Result<()>

Connects this UDP socket to a remote address, allowing the send and recv to be used to send data and also applies filters to only receive data from the specified address.

Note that usually, a successful connect call does not specify that there is a remote server listening on the port, rather, such an error would only be detected after the first send.

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

Creates new UdpSocket from a std::net::UdpSocket.

pub fn close(self) -> impl Future<Output = Result<()>>

Close the socket. If the returned future is dropped before polling, the socket won’t be closed.

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

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

Examples

use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4};

use compio_net::UdpSocket;
use socket2::SockAddr;

let socket = UdpSocket::bind("127.0.0.1:34254")
    .await
    .expect("couldn't bind to address");
socket
    .connect("192.168.0.1:41203")
    .await
    .expect("couldn't connect to address");
assert_eq!(
    socket.peer_addr().unwrap(),
    SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(192, 168, 0, 1), 41203))
);

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

Returns the local address that this socket is bound to.

Example

use std::net::SocketAddr;

use compio_net::UdpSocket;
use socket2::SockAddr;

let addr: SocketAddr = "127.0.0.1:8080".parse().unwrap();
let sock = UdpSocket::bind(&addr).await.unwrap();
// the address the socket is bound to
let local_addr = sock.local_addr().unwrap();
assert_eq!(local_addr, addr);

pub async fn recv<T: IoBufMut>(&self, buffer: T) -> BufResult<usize, T>

Receives a packet of data from the socket into the buffer, returning the original buffer and quantity of data received.

pub async fn recv_vectored<T: IoVectoredBufMut>( &self, buffer: T, ) -> BufResult<usize, T>

Receives a packet of data from the socket into the buffer, returning the original buffer and quantity of data received.

pub async fn send<T: IoBuf>(&self, buffer: T) -> BufResult<usize, T>

Sends some data to the socket from the buffer, returning the original buffer and quantity of data sent.

pub async fn send_vectored<T: IoVectoredBuf>( &self, buffer: T, ) -> BufResult<usize, T>

Sends some data to the socket from the buffer, returning the original buffer and quantity of data sent.

pub async fn recv_from<T: IoBufMut>( &self, buffer: T, ) -> BufResult<(usize, SocketAddr), T>

Receives a single datagram message on the socket. On success, returns the number of bytes received and the origin.

pub async fn recv_from_vectored<T: IoVectoredBufMut>( &self, buffer: T, ) -> BufResult<(usize, SocketAddr), T>

Receives a single datagram message on the socket. On success, returns the number of bytes received and the origin.

pub async fn recv_msg<T: IoBufMut, C: IoBufMut>( &self, buffer: T, control: C, ) -> BufResult<(usize, usize, SocketAddr), (T, C)>

Receives a single datagram message and ancillary data on the socket. On success, returns the number of bytes received and the origin.

pub async fn recv_msg_vectored<T: IoVectoredBufMut, C: IoBufMut>( &self, buffer: T, control: C, ) -> BufResult<(usize, usize, SocketAddr), (T, C)>

Receives a single datagram message and ancillary data on the socket. On success, returns the number of bytes received and the origin.

pub async fn send_to<T: IoBuf>( &self, buffer: T, addr: impl ToSocketAddrsAsync, ) -> BufResult<usize, T>

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

pub async fn send_to_vectored<T: IoVectoredBuf>( &self, buffer: T, addr: impl ToSocketAddrsAsync, ) -> BufResult<usize, T>

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

pub async fn send_msg<T: IoBuf, C: IoBuf>( &self, buffer: T, control: C, addr: impl ToSocketAddrsAsync, ) -> BufResult<usize, (T, C)>

Sends data on the socket to the given address accompanied by ancillary data. On success, returns the number of bytes sent.

pub async fn send_msg_vectored<T: IoVectoredBuf, C: IoBuf>( &self, buffer: T, control: C, addr: impl ToSocketAddrsAsync, ) -> BufResult<usize, (T, C)>

Sends data on the socket to the given address accompanied by ancillary data. On success, returns the number of bytes sent.

pub unsafe fn get_socket_option<T: Copy>( &self, level: i32, name: i32, ) -> Result<T>

Gets a socket option.

Safety

The caller must ensure T is the correct type for level and name.

pub unsafe fn set_socket_option<T: Copy>( &self, level: i32, name: i32, value: &T, ) -> Result<()>

Sets a socket option.

Safety

The caller must ensure T is the correct type for level and name.

Trait Implementations

impl AsRawFd for UdpSocket

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Clone for UdpSocket

fn clone(&self) -> UdpSocket

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UdpSocket

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

Formats the value using the given formatter.

impl FromRawFd for UdpSocket

Available on Unix only.

unsafe fn from_raw_fd(fd: RawFd) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl ToSharedFd<Socket> for UdpSocket

fn to_shared_fd(&self) -> SharedFd<Socket>

Return a cloned SharedFd.