[−][src]Struct tokio::net::UdpSocket
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
[src]
pub async fn bind<A: ToSocketAddrs>(addr: A) -> Result<UdpSocket>
[src]
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>
[src]
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>
[src]
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<()>
[src]
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>
[src]
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>
[src]
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>
[src]
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>
[src]
&'_ self,
buf: &'_ [u8],
target: A
) -> Result<usize>
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>
[src]
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)>
[src]
&'_ self,
buf: &'_ mut [u8]
) -> Result<(usize, SocketAddr)>
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>
[src]
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<()>
[src]
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>
[src]
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<()>
[src]
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>
[src]
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<()>
[src]
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>
[src]
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<()>
[src]
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>
[src]
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<()>
[src]
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<()>
[src]
&self,
multiaddr: Ipv4Addr,
interface: Ipv4Addr
) -> Result<()>
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<()>
[src]
&self,
multiaddr: &Ipv6Addr,
interface: u32
) -> Result<()>
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<()>
[src]
&self,
multiaddr: Ipv4Addr,
interface: Ipv4Addr
) -> Result<()>
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<()>
[src]
&self,
multiaddr: &Ipv6Addr,
interface: u32
) -> Result<()>
net
only.Executes an operation of the IPV6_DROP_MEMBERSHIP
type.
For more information about this option, see join_multicast_v6
.
Trait Implementations
impl AsRawSocket for UdpSocket
[src]
fn as_raw_socket(&self) -> RawSocket
[src]
impl Debug for UdpSocket
[src]
impl TryFrom<UdpSocket> for UdpSocket
[src]
Auto Trait Implementations
impl !RefUnwindSafe for UdpSocket
impl Send for UdpSocket
impl Sync for UdpSocket
impl Unpin for UdpSocket
impl !UnwindSafe for UdpSocket
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut Tⓘ
[src]
impl<T> From<T> for T
[src]
impl<T> Instrument for T
[src]
fn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>
impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
[src]
Notable traits for Instrumented<T>
impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>
impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
[src]
Notable traits for Instrumented<T>
impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,