Struct UdpSocket

pub struct UdpSocket { /* private fields */ }

Available on crate feature 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. 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<UdpSocket, Error>

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

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

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

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

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

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

See TcpStream::close for more details.

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

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

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>(&self, buffer: T) -> BufResult<usize, T>
where T: IoBufMut,

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>(&self, buffer: T) -> BufResult<usize, T>
where T: IoVectoredBufMut,

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

pub async fn recv_managed(&self, len: usize) -> Result<Option<BufferRef>, Error>

Read some bytes from this source and return a BufferRef.

If len == 0, will use buffer pool’s inner buffer size as the max len; if len > 0, min(len, inner buffer size) will be the read max len.

pub fn recv_multi( &self, len: usize, ) -> impl Stream<Item = Result<BufferRef, Error>>

Read some bytes from this source and return a stream of BufferRefs.

If len == 0, will use buffer pool’s inner buffer size as the max len of each buffer; if len > 0, min(len, inner buffer size) will be the read max len of each buffer.

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

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

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

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

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

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>( &self, buffer: T, ) -> BufResult<(usize, SocketAddr), T>
where T: IoVectoredBufMut,

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

pub async fn recv_from_managed( &self, len: usize, ) -> Result<Option<(BufferRef, SocketAddr)>, Error>

Read some bytes from this source and the runtime’s buffer pool and return a BufferRef with the sender address.

If len == 0, will use buffer pool’s inner buffer size as the max len; if len > 0, min(len, inner buffer size) will be the read max len

pub fn recv_from_multi( &self, ) -> impl Stream<Item = Result<RecvFromMultiResult, Error>>

Read some bytes from this source and the runtime’s buffer pool and return a stream of RecvFromMultiResult.

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

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, C>( &self, buffer: T, control: C, ) -> BufResult<(usize, usize, SocketAddr), (T, C)>
where T: IoVectoredBufMut, C: IoBufMut,

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_managed<C>( &self, len: usize, control: C, ) -> Result<Option<(BufferRef, C, SocketAddr)>, Error>
where C: IoBufMut,

Receives a single datagram message on the socket from the runtime’s buffer pool, together with ancillary data. The ancillary data buffer is provided by the caller.

If len == 0, will use buffer pool’s inner buffer size as the max len; if len > 0, min(len, inner buffer size) will be the read max len

pub fn recv_msg_multi( &self, control_len: usize, ) -> impl Stream<Item = Result<RecvMsgMultiResult, Error>>

Receives multiple single datagram messages and ancillary data on the socket from the runtime’s buffer pool.

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

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

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

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

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

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, C>( &self, buffer: T, control: C, addr: impl ToSocketAddrsAsync, ) -> BufResult<usize, (T, C)>
where T: IoVectoredBuf, C: IoBuf,

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