Struct heph::net::udp::UdpSocket

pub struct UdpSocket<M = Unconnected> { /* fields omitted */ }

A User Datagram Protocol (UDP) socket.

To create a UDP socket UdpSocket::bind can be used, this will bind the socket to a local address. The created socket will be in unconnected mode. A socket can be in one of two modes:

• Unconnected mode allows sending and receiving packets to and from all sources.
• Connected mode only allows sending and receiving packets from/to a single source.

An unconnected socket can be connected to a specific address if needed, changing the mode to Connected in the process. The remote address of an already connected socket can be changed to a different address using the same method.

Both unconnected and connected sockets have three main operations send, receive and peek, all these methods return a Future.

Examples

#![feature(never_type)]

use std::net::SocketAddr;
use std::{io, str};

use log::error;

use heph::actor::messages::Terminate;
use heph::net::UdpSocket;
use heph::rt::{self, Runtime, RuntimeRef, ThreadLocal};
use heph::spawn::ActorOptions;
use heph::util::either;
use heph::{actor, SupervisorStrategy};

fn main() -> Result<(), rt::Error> {
    std_logger::init();

    let mut runtime = Runtime::new()?;
    runtime.run_on_workers(setup)?;
    runtime.start()
}

fn setup(mut runtime: RuntimeRef) -> Result<(), !> {
    let address = "127.0.0.1:7000".parse().unwrap();
    // Add our server actor.
    runtime.spawn_local(supervisor, echo_server as fn(_, _) -> _, address, ActorOptions::default());
    // Add our client actor.
    runtime.spawn_local(supervisor, client as fn(_, _) -> _, address, ActorOptions::default());
    Ok(())
}

/// Simple supervisor that logs the error and stops the actor.
fn supervisor<Arg>(err: io::Error) -> SupervisorStrategy<Arg> {
    error!("Encountered an error: {}", err);
    SupervisorStrategy::Stop
}

/// Actor that will bind a UDP socket and waits for incoming packets and
/// echos the message to standard out.
async fn echo_server(mut ctx: actor::Context<Terminate, ThreadLocal>, local: SocketAddr) -> io::Result<()> {
    let mut socket = UdpSocket::bind(&mut ctx, local)?;
    let mut buf = Vec::with_capacity(4096);
    loop {
        buf.clear();
        let receive_msg = ctx.receive_next();
        let read = socket.recv_from(&mut buf);
        let address = match either(read, receive_msg).await {
            // Received a packet.
            Ok(Ok((_, address))) => address,
            // Read error.
            Ok(Err(err)) => return Err(err),
            // If we receive a terminate message we'll stop the actor.
            Err(_) => return Ok(()),
        };

        match str::from_utf8(&buf) {
            Ok(str) => println!("Got the following message: `{}`, from {}", str, address),
            Err(_) => println!("Got data: {:?}, from {}", buf, address),
        }
    }
}

/// The client that will send a message to the server.
async fn client(mut ctx: actor::Context<!, ThreadLocal>, server_address: SocketAddr) -> io::Result<()> {
    let local_address = "127.0.0.1:7001".parse().unwrap();
    let mut socket = UdpSocket::bind(&mut ctx, local_address)
        .and_then(|socket| socket.connect(server_address))?;

    let msg = b"Hello world";
    let n = socket.send(&*msg).await?;
    assert_eq!(n, msg.len());
    Ok(())
}

Implementations

impl UdpSocket

pub fn bind<M, RT>(
    ctx: &mut Context<M, RT>,
    local: SocketAddr
) -> Result<UdpSocket<Unconnected>> where
    RT: Access, 

Create a UDP socket binding to the local address.

Notes

The UDP socket is also bound to the actor that owns the actor::Context, which means the actor will be run every time the socket is ready to be read from or write to.

impl<M> UdpSocket<M>

pub fn connect(self, remote: SocketAddr) -> Result<UdpSocket<Connected>>

Connects the UDP socket by setting the default destination and limiting packets that are read, written and peeked to the remote address.

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

Returns the sockets local address.

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

Get the value of the SO_ERROR option on this socket.

This will retrieve the stored error in the underlying socket, clearing the field in the process. This can be useful for checking errors between calls.

impl UdpSocket<Unconnected>

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

Attempt to send data to the given target address.

If the buffer currently can’t be send this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::send_to.

pub fn send_to<'a, 'b>(
    &'a mut self,
    buf: &'b [u8],
    target: SocketAddr
) -> SendTo<'a, 'b>

Sends data to the given target address. Returns a Future that on success returns the number of bytes written (io::Result<usize>).

pub fn try_send_to_vectored(
    &mut self,
    bufs: &[IoSlice<'_>],
    target: SocketAddr
) -> Result<usize>

Attempt to send bytes in bufs to the peer.

If no bytes can currently be send this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::send_to_vectored.

pub fn send_to_vectored<'a, 'b>(
    &'a mut self,
    bufs: &'b mut [IoSlice<'b>],
    target: SocketAddr
) -> SendToVectored<'a, 'b>

Send the bytes in bufs to the peer.

Returns the number of bytes written. This may be fewer then the length of bufs.

pub fn try_recv_from<B>(&mut self, buf: B) -> Result<(usize, SocketAddr)> where
    B: Bytes, 

Attempt to receive data from the socket, writing them into buf.

If no bytes can currently be received this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::recv_from.

pub fn recv_from<B>(&mut self, buf: B) -> RecvFrom<'_, B> where
    B: Bytes, 

Receives data from the socket. Returns a Future that on success returns the number of bytes read and the address from whence the data came (io::Result<(usize, SocketAddr>).

pub fn try_recv_from_vectored<B>(
    &mut self,
    bufs: B
) -> Result<(usize, SocketAddr)> where
    B: BytesVectored, 

Attempt to receive data from the socket, writing them into bufs.

If no bytes can currently be received this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::recv_from.

pub fn recv_from_vectored<B>(&mut self, bufs: B) -> RecvFromVectored<'_, B> where
    B: BytesVectored, 

Receives data from the socket. Returns a Future that on success returns the number of bytes read and the address from whence the data came (io::Result<(usize, SocketAddr>).

pub fn try_peek_from<B>(&mut self, buf: B) -> Result<(usize, SocketAddr)> where
    B: Bytes, 

Attempt to peek data from the socket, writing them into buf.

If no bytes can currently be peeked this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::peek_from.

pub fn peek_from<B>(&mut self, buf: B) -> PeekFrom<'_, B> where
    B: Bytes, 

Receives data from the socket, without removing it from the input queue. Returns a Future that on success returns the number of bytes read and the address from whence the data came (io::Result<(usize, SocketAddr>).

pub fn try_peek_from_vectored<B>(
    &mut self,
    bufs: B
) -> Result<(usize, SocketAddr)> where
    B: BytesVectored, 

Attempt to peek data from the socket, writing them into bufs.

If no bytes can currently be received this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::recv_vectored.

pub fn peek_from_vectored<B>(&mut self, bufs: B) -> PeekFromVectored<'_, B> where
    B: BytesVectored, 

Receives data from the socket, without removing it from the input queue. Returns a Future that on success returns the number of bytes read and the address from whence the data came (io::Result<(usize, SocketAddr>).

impl UdpSocket<Connected>

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

Attempt to send data to the peer.

If the buffer currently can’t be send this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::send_to.

pub fn send<'a, 'b>(&'a mut self, buf: &'b [u8]) -> Send<'a, 'b>

Sends data on the socket to the connected socket. Returns a Future that on success returns the number of bytes written (io::Result<usize>).

pub fn try_send_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Attempt to send bytes in bufs to the peer.

If no bytes can currently be send this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::send_vectored.

pub fn send_vectored<'a, 'b>(
    &'a mut self,
    bufs: &'b mut [IoSlice<'b>]
) -> SendVectored<'a, 'b>

Send the bytes in bufs to the peer.

Returns the number of bytes written. This may we fewer then the length of bufs.

pub fn try_recv<B>(&mut self, buf: B) -> Result<usize> where
    B: Bytes, 

Attempt to receive data from the socket, writing them into buf.

If no bytes can currently be received this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::recv.

pub fn recv<B>(&mut self, buf: B) -> Recv<'_, B> where
    B: Bytes, 

Receives data from the socket. Returns a Future that on success returns the number of bytes read (io::Result<usize>).

pub fn try_recv_vectored<B>(&mut self, bufs: B) -> Result<usize> where
    B: BytesVectored, 

Attempt to receive data from the socket, writing them into bufs.

If no bytes can currently be received this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::recv_vectored.

pub fn recv_vectored<B>(&mut self, bufs: B) -> RecvVectored<'_, B> where
    B: BytesVectored, 

Receives data from the socket. Returns a Future that on success returns the number of bytes read (io::Result<usize>).

pub fn try_peek<B>(&mut self, buf: B) -> Result<usize> where
    B: Bytes, 

Attempt to peek data from the socket, writing them into buf.

If no bytes can currently be peeked this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::peek.

pub fn peek<B>(&mut self, buf: B) -> Peek<'_, B> where
    B: Bytes, 

Receives data from the socket, without removing it from the input queue. Returns a Future that on success returns the number of bytes read (io::Result<usize>).

pub fn try_peek_vectored<B>(&mut self, bufs: B) -> Result<usize> where
    B: BytesVectored, 

Attempt to peek data from the socket, writing them into bufs.

If no bytes can currently be received this will return an error with the kind set to ErrorKind::WouldBlock. Most users should prefer to use UdpSocket::recv_vectored.

pub fn peek_vectored<B>(&mut self, bufs: B) -> PeekVectored<'_, B> where
    B: BytesVectored, 

Receives data from the socket, without removing it from the input queue. Returns a Future that on success returns the number of bytes read (io::Result<usize>).

Trait Implementations

impl<RT: Access> Bound<RT> for UdpSocket

type Error = Error

Error type used in bind_to.

fn bind_to<M>(&mut self, ctx: &mut Context<M, RT>) -> Result<()>

Bind a type to the Actor that owns the ctx.

impl<M> Debug for UdpSocket<M>

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

Formats the value using the given formatter.