Структура UdpSocket

Эта функция создаёт новый UDP-сокет и пытается привязать его к указанному addr.

Привязка к порту со значением 0 запрашивает назначение порта операционной системой для этого слушателя. Выделенный порт можно запросить с помощью метода local_addr.

Пример

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(())
}

Создаёт новый UdpSocket из ранее привязанного std::net::UdpSocket.

Эта функция предназначена для оборачивания UDP-сокета из стандартной библиотеки в эквивалент Tokio.

Это можно использовать в сочетании с интерфейсом Socket библиотеки socket2 для настройки сокета перед его передачей, например, установки таких параметров, как reuse_address, или привязки к нескольким адресам.

Примечания

Вызывающая сторона отвечает за то, чтобы сокет находился в неблокирующем режиме. В противном случае все операции ввода-вывода на сокете будут блокировать поток, что приведёт к неожиданному поведению. Неблокирующий режим можно установить с помощью set_nonblocking.

Передача слушателя в блокирующем режиме всегда ошибочна, и поведение в этом случае может измениться в будущем. Например, это может вызвать панику.

Паника

Эта функция вызывает панику, если среда выполнения для текущего потока не установлена.

Среда выполнения обычно устанавливается неявно, когда эта функция вызывается из future, управляемой средой выполнения tokio, в противном случае среду выполнения можно установить явно с помощью функции Runtime::enter.

Пример

use tokio::net::UdpSocket;

let addr = "0.0.0.0:8080".parse::<SocketAddr>().unwrap();
let std_sock = std::net::UdpSocket::bind(addr)?;
std_sock.set_nonblocking(true)?;
let sock = UdpSocket::from_std(std_sock)?;
// use `sock`

Преобразует tokio::net::UdpSocket в std::net::UdpSocket.

Возвращённый std::net::UdpSocket будет иметь неблокирующий режим со значением true. Используйте set_nonblocking, чтобы при необходимости изменить режим блокировки.

Примеры

use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let tokio_socket = tokio::net::UdpSocket::bind("127.0.0.1:0").await?;
    let std_socket = tokio_socket.into_std()?;
    std_socket.set_nonblocking(false)?;
    Ok(())
}

Возвращает локальный адрес, к которому привязан этот сокет.

Пример

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()?;

Возвращает адрес сокета удалённого узла, к которому был подключён этот сокет.

Пример

use tokio::net::UdpSocket;

let addr = "0.0.0.0:8080".parse::<SocketAddr>().unwrap();
let peer = "127.0.0.1:11100".parse::<SocketAddr>().unwrap();
let sock = UdpSocket::bind(addr).await?;
sock.connect(peer).await?;
assert_eq!(peer, sock.peer_addr()?);

Подключает UDP-сокет, устанавливая адрес назначения по умолчанию для send() и ограничивая пакеты, считываемые через recv, адресом, указанным в addr.

Пример

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?;

Ожидает любого из запрошенных состояний готовности.

Эта функция обычно используется в паре с try_recv() или try_send(). Её можно использовать для конкурентного выполнения recv / send с одним и тем же сокетом в рамках одной задачи без разделения сокета.

Функция может завершиться, даже если сокет не готов. Это ложноположительное срабатывание, и попытка выполнить операцию вернёт io::ErrorKind::WouldBlock. Функция также может вернуть пустой набор Ready, поэтому вам всегда следует проверять возвращённое значение и, при необходимости, ожидать снова, если запрошенные состояния не установлены.

Безопасность отмены

Этот метод безопасен для отмены. Как только происходит событие готовности, метод будет продолжать немедленно возвращать управление до тех пор, пока событие готовности не будет исчерпано попыткой чтения или записи, которая завершится с ошибкой WouldBlock или Poll::Pending.

Примеры

Конкурентный приём и отправка данных через сокет в одной задаче без его разделения.

use tokio::io::{self, Interest};
use tokio::net::UdpSocket;

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

    loop {
        let ready = socket.ready(Interest::READABLE | Interest::WRITABLE).await?;

        if ready.is_readable() {
            // The buffer is **not** included in the async task and will only exist
            // on the stack.
            let mut data = [0; 1024];
            match socket.try_recv(&mut data[..]) {
                Ok(n) => {
                    println!("received {:?}", &data[..n]);
                }
                // False-positive, continue
                Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {}
                Err(e) => {
                    return Err(e);
                }
            }
        }

        if ready.is_writable() {
            // Write some data
            match socket.try_send(b"hello world") {
                Ok(n) => {
                    println!("sent {} bytes", n);
                }
                // False-positive, continue
                Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {}
                Err(e) => {
                    return Err(e);
                }
            }
        }
    }
}

Ожидает, пока сокет станет доступен для записи.

Эта функция эквивалентна ready(Interest::WRITABLE) и обычно используется в паре с try_send() или try_send_to().

Функция может завершиться, даже если сокет не стал доступен для записи. Это ложноположительное срабатывание, и попытка выполнить try_send() вернёт io::ErrorKind::WouldBlock.

Безопасность отмены

Этот метод безопасен для отмены. Как только происходит событие готовности, метод будет продолжать немедленно возвращать управление до тех пор, пока событие готовности не будет исчерпано попыткой записи, которая завершится с ошибкой WouldBlock или Poll::Pending.

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Bind socket
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;
    socket.connect("127.0.0.1:8081").await?;

    loop {
        // Wait for the socket to be writable
        socket.writable().await?;

        // Try to send data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_send(b"hello world") {
            Ok(n) => {
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}

Опрашивает готовность к записи/отправке.

Если UDP-поток в данный момент не готов к отправке, этот метод сохранит клон Waker из предоставленного Context. Когда UDP-поток станет готов к отправке, для waker будет вызван Waker::wake.

Обратите внимание, что при многократных вызовах poll_send_ready или poll_send только Waker из Context, переданного в самый последний вызов, запланирован для получения пробуждения. (Однако poll_recv_ready сохраняет второй, независимый waker.)

Эта функция предназначена для случаев, когда создание и закрепление (pinning) future с помощью writable нецелесообразно. По возможности рекомендуется использовать writable, так как это поддерживает опрос из нескольких задач одновременно.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если UDP-поток не готов к записи.
• Poll::Ready(Ok(())), если UDP-поток готов к записи.
• Poll::Ready(Err(e)), если возникла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, кроме WouldBlock.

Отправляет данные через сокет на удалённый адрес, к которому подключён сокет.

Метод connect подключает этот сокет к удалённому адресу. Этот метод завершится ошибкой, если сокет не подключён.

Этот метод может завершиться ошибкой ConnectionRefused, если удалённый адрес ответил пакетом ICMP Unreachable на ранее отправленный пакет. Однако это поведение зависит от ОС.

Возвращаемое значение

В случае успеха возвращается количество отправленных байтов, в противном случае возвращается возникшая ошибка.

Безопасность отмены

Этот метод безопасен для отмены. Если send используется в качестве ветки в tokio::select! и другая ветка завершается первой, то гарантируется, что сообщение не было отправлено.

Примеры

use tokio::io;
use tokio::net::UdpSocket;

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

Пытается отправить данные через сокет на удалённый адрес, к которому он ранее был connected.

Метод connect подключает этот сокет к удалённому адресу. Этот метод завершится с ошибкой, если сокет не подключен.

Обратите внимание, что при нескольких вызовах метода poll_* в направлении отправки только Waker из Context, переданного в самый последний вызов, будет запланирован для получения пробуждения.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если сокет недоступен для записи
• Poll::Ready(Ok(n)) n — количество отправленных байтов
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, кроме WouldBlock.

Пытается отправить данные через сокет на удалённый адрес, к которому он подключен.

Когда буфер сокета заполнен, возвращается Err(io::ErrorKind::WouldBlock). Эта функция обычно используется в паре с writable().

Возвращает

В случае успеха возвращается Ok(n), где n — количество отправленных байтов. Если сокет не готов к отправке данных, возвращается Err(ErrorKind::WouldBlock).

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Bind a UDP socket
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;

    // Connect to a peer
    socket.connect("127.0.0.1:8081").await?;

    loop {
        // Wait for the socket to be writable
        socket.writable().await?;

        // Try to send data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_send(b"hello world") {
            Ok(n) => {
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}

Ожидает, пока сокет станет доступным для чтения.

Эта функция эквивалентна ready(Interest::READABLE) и обычно используется в паре с try_recv().

Функция может завершиться, даже если сокет не готов к чтению. Это ложное срабатывание, и попытка вызова try_recv() вернёт io::ErrorKind::WouldBlock.

Безопасность отмены

Этот метод безопасен для отмены. Как только произойдет событие готовности, метод будет продолжать немедленно возвращать результат до тех пор, пока событие готовности не будет сброшено попыткой чтения, завершившейся с ошибкой WouldBlock или Poll::Pending.

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;
    socket.connect("127.0.0.1:8081").await?;

    loop {
        // Wait for the socket to be readable
        socket.readable().await?;

        // The buffer is **not** included in the async task and will
        // only exist on the stack.
        let mut buf = [0; 1024];

        // Try to recv data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_recv(&mut buf) {
            Ok(n) => {
                println!("GOT {:?}", &buf[..n]);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}

Опрашивает готовность к чтению/приёму.

Если UDP-поток в данный момент не готов к приёму, этот метод сохранит клон Waker из предоставленного Context. Когда UDP-сокет станет готов к чтению, для waker будет вызван метод Waker::wake.

Обратите внимание, что при нескольких вызовах poll_recv_ready, poll_recv или poll_peek только Waker из Context, переданного в самый последний вызов, будет запланирован для получения пробуждения. (Однако poll_send_ready сохраняет второй, независимый waker.)

Эта функция предназначена для случаев, когда создание и закрепление future через readable нецелесообразно. По возможности рекомендуется использовать readable, так как это поддерживает опрос из нескольких задач одновременно.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если UDP-поток не готов к чтению.
• Poll::Ready(Ok(())), если UDP-поток готов к чтению.
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, кроме WouldBlock.

Принимает одно сообщение датаграммы на сокете от удалённого адреса, к которому он подключен. В случае успеха возвращает количество прочитанных байтов.

Функция должна вызываться с допустимым байтовым массивом buf достаточного размера, чтобы вместить байты сообщения. Если сообщение слишком длинное и не помещается в предоставленный буфер, лишние байты могут быть отброшены.

Метод connect подключает этот сокет к удалённому адресу. Этот метод завершится с ошибкой, если сокет не подключен.

Безопасность отмены

Этот метод безопасен для отмены. Если recv используется в качестве ветви в tokio::select! и другая ветвь завершается первой, гарантируется, что на этот сокет не было получено никаких сообщений.

use tokio::net::UdpSocket;
use std::io;

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

Пытается принять одно сообщение датаграммы на сокете от удалённого адреса, к которому он connected.

Метод connect подключает этот сокет к удалённому адресу. Этот метод возвращает ошибку, если сокет не подключен.

Обратите внимание, что при нескольких вызовах метода poll_* в направлении recv только Waker из Context, переданного в самый последний вызов, будет запланирован для получения пробуждения.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если сокет не готов к чтению
• Poll::Ready(Ok(())) считывает данные в ReadBuf, если сокет готов
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, кроме WouldBlock.

Пытается принять одно сообщение датаграммы на сокете от удалённого адреса, к которому он подключен. В случае успеха возвращает количество прочитанных байтов.

Этот метод должен вызываться с допустимым байтовым массивом buf достаточного размера, чтобы вместить байты сообщения. Если сообщение слишком длинное и не помещается в предоставленный буфер, лишние байты могут быть отброшены.

Когда нет ожидающих данных, возвращается Err(io::ErrorKind::WouldBlock). Эта функция обычно используется в паре с readable().

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;
    socket.connect("127.0.0.1:8081").await?;

    loop {
        // Wait for the socket to be readable
        socket.readable().await?;

        // The buffer is **not** included in the async task and will
        // only exist on the stack.
        let mut buf = [0; 1024];

        // Try to recv data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_recv(&mut buf) {
            Ok(n) => {
                println!("GOT {:?}", &buf[..n]);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}

Пытается принять данные из потока в предоставленный буфер, перемещая внутренний курсор буфера вперёд, и возвращает количество прочитанных байтов.

Этот метод должен вызываться с допустимым байтовым массивом buf достаточного размера, чтобы вместить байты сообщения. Если сообщение слишком длинное и не помещается в предоставленный буфер, лишние байты могут быть отброшены.

Этот метод можно использовать, даже если buf не инициализирован.

Когда нет ожидающих данных, возвращается Err(io::ErrorKind::WouldBlock). Эта функция обычно используется в паре с readable().

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;
    socket.connect("127.0.0.1:8081").await?;

    loop {
        // Wait for the socket to be readable
        socket.readable().await?;

        let mut buf = Vec::with_capacity(1024);

        // Try to recv data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_recv_buf(&mut buf) {
            Ok(n) => {
                println!("GOT {:?}", &buf[..n]);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}

Принимает одно сообщение датаграммы на сокете от удалённого адреса, к которому он подключен, перемещая внутренний курсор буфера вперёд, и возвращает количество прочитанных байтов.

Этот метод должен вызываться с допустимым байтовым массивом buf достаточного размера, чтобы вместить байты сообщения. Если сообщение слишком длинное и не помещается в предоставленный буфер, лишние байты могут быть отброшены.

Этот метод можно использовать, даже если buf не инициализирован.

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    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(())
}

Пытается принять одно датаграммное сообщение на сокете. В случае успеха возвращает количество прочитанных байтов и адрес отправителя.

Этот метод должен вызываться с корректным массивом байтов buf достаточного размера, чтобы вместить байты сообщения. Если сообщение слишком длинное и не помещается в предоставленный буфер, лишние байты могут быть отброшены.

Этот метод можно использовать, даже если buf не инициализирован.

Если нет ожидающих данных, возвращается Err(io::ErrorKind::WouldBlock). Обычно эта функция используется в паре с readable().

Примечания

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным адресом отправителя в ходе атаки с внедрением пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику не требуется возможность перехватывать трафик для вмешательства. Важно помнить об этом при разработке протокола прикладного уровня.

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;

    loop {
        // Wait for the socket to be readable
        socket.readable().await?;

        let mut buf = Vec::with_capacity(1024);

        // Try to recv data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_recv_buf_from(&mut buf) {
            Ok((n, _addr)) => {
                println!("GOT {:?}", &buf[..n]);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}

Принимает одно датаграммное сообщение на сокете, перемещая внутренний курсор буфера вперёд, и возвращает количество прочитанных байтов и адрес отправителя.

Этот метод должен вызываться с корректным массивом байтов buf достаточного размера, чтобы вместить байты сообщения. Если сообщение слишком длинное и не помещается в предоставленный буфер, лишние байты могут быть отброшены.

Этот метод можно использовать, даже если buf не инициализирован.

Примечания

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным адресом отправителя в ходе атаки с внедрением пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику не требуется возможность перехватывать трафик для вмешательства. Важно помнить об этом при разработке протокола прикладного уровня.

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    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(())
}

Отправляет данные через сокет на указанный адрес. В случае успеха возвращает количество записанных байтов.

Типом адреса может быть любой тип, реализующий типаж ToSocketAddrs. Конкретные примеры приведены в его документации.

addr может возвращать несколько адресов, но send_to отправит данные только на первый адрес, возвращённый addr.

Этот метод вернёт ошибку, если версия IP локального сокета не совпадает с версией IP, возвращённой из ToSocketAddrs.

Безопасность отмены

Этот метод безопасен к отмене. Если send_to используется в качестве ветки в tokio::select!, и другая ветка завершается первой, гарантируется, что сообщение не было отправлено.

Пример

use tokio::net::UdpSocket;
use std::io;

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

Пытается отправить данные через сокет на указанный адрес.

Обратите внимание, что при многократных вызовах метода poll_* в направлении отправки только Waker из Context, переданного в последний вызов, будет запланирован для получения пробуждения.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если сокет не готов к записи
• Poll::Ready(Ok(n)) n — количество отправленных байтов.
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, за исключением WouldBlock.

Пытается отправить данные через сокет на указанный адрес, но если отправка блокируется, метод сразу же возвращает управление.

Обычно эта функция используется в паре с writable().

Возвращаемое значение

В случае успеха возвращает количество отправленных байтов

Пользователи должны убедиться, что в ситуации, когда удалённая сторона не может принять данные, ошибка ErrorKind::WouldBlock обрабатывается должным образом. Ошибка также может возникнуть, если версия IP сокета не совпадает с версией IP у target.

Пример

use tokio::net::UdpSocket;
use std::error::Error;
use std::io;

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

    let dst = "127.0.0.1:8081".parse()?;

    loop {
        socket.writable().await?;

        match socket.try_send_to(&b"hello world"[..], dst) {
            Ok(sent) => {
                println!("sent {} bytes", sent);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                // Writable false positive.
                continue;
            }
            Err(e) => return Err(e.into()),
        }
    }

    Ok(())
}

Принимает одно датаграммное сообщение на сокете. В случае успеха возвращает количество прочитанных байтов и адрес отправителя.

Функция должна вызываться с корректным массивом байтов buf достаточного размера, чтобы вместить байты сообщения. Если сообщение слишком длинное и не помещается в предоставленный буфер, лишние байты могут быть отброшены.

Безопасность отмены

Этот метод безопасен к отмене. Если recv_from используется в качестве ветки в tokio::select!, и другая ветка завершается первой, гарантируется, что на этот сокет не было принято никаких сообщений.

Пример

use tokio::net::UdpSocket;
use std::io;

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

Примечания

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным адресом отправителя в ходе атаки с внедрением пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику не требуется возможность перехватывать трафик для вмешательства. Важно помнить об этом при разработке протокола прикладного уровня.

Пытается принять одну датаграмму на сокете.

Обратите внимание, что при многократных вызовах метода poll_* в направлении recv только Waker из Context, переданного в последний вызов, будет запланирован для получения пробуждения.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если сокет не готов к чтению
• Poll::Ready(Ok(addr)) читает данные из addr в ReadBuf, если сокет готов
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, за исключением WouldBlock.

Примечания

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным адресом отправителя в ходе атаки с внедрением пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику не требуется возможность перехватывать трафик для вмешательства. Важно помнить об этом при разработке протокола прикладного уровня.

Пытается принять одно датаграммное сообщение из сокета. В случае успеха возвращает количество прочитанных байтов и адрес отправителя.

Этот метод должен вызываться с корректным массивом байтов buf достаточного размера для хранения байтов сообщения. Если сообщение слишком велико, чтобы поместиться в предоставленный буфер, лишние байты могут быть отброшены.

Когда нет ожидающих данных, возвращается Err(io::ErrorKind::WouldBlock). Эта функция обычно используется в паре с readable().

Примечания

Обратите внимание, что адресу сокета нельзя слепо доверять, поскольку отправить датаграмму UDP с поддельным адресом отправителя с помощью атаки внедрения пакетов относительно просто. Поскольку протокол UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола на уровне приложения.

Примеры

use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;

    loop {
        // Wait for the socket to be readable
        socket.readable().await?;

        // The buffer is **not** included in the async task and will
        // only exist on the stack.
        let mut buf = [0; 1024];

        // Try to recv data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_recv_from(&mut buf) {
            Ok((n, _addr)) => {
                println!("GOT {:?}", &buf[..n]);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}

Пытается выполнить чтение или запись из сокета с помощью предоставленной пользователем операции ввода-вывода.

Если сокет готов, вызывается предоставленное замыкание. Замыкание должно попытаться выполнить операцию ввода-вывода на сокете, вручную вызвав соответствующий системный вызов. Если операция завершается неудачно из-за того, что сокет фактически не готов, замыкание должно вернуть ошибку WouldBlock, и флаг готовности будет сброшен. Затем возвращаемое значение замыкания возвращается методом try_io.

Если сокет не готов, замыкание не вызывается и возвращается ошибка WouldBlock.

Замыкание должно возвращать ошибку WouldBlock только в том случае, если оно выполнило операцию ввода-вывода на сокете, которая завершилась неудачей из-за неготовности сокета. Возврат ошибки WouldBlock в любой другой ситуации ошибочно сбросит флаг готовности, что может привести к некорректной работе сокета.

Замыкание не должно выполнять операцию ввода-вывода с использованием каких-либо методов, определенных для типа UdpSocket из Tokio, так как это нарушит работу флага готовности и может привести к некорректному поведению сокета.

Этот метод не предназначен для использования с комбинированными событиями интереса (interests). Замыкание должно выполнять только один тип операций ввода-вывода, поэтому оно не должно требовать более одного состояния готовности. Этот метод может вызвать панику или заблокироваться навсегда при вызове с комбинированным интересом.

Обычно с этой функцией используются readable(), writable() или ready().

Выполняет чтение или запись из сокета с помощью предоставленной пользователем операции ввода-вывода.

Ожидается готовность сокета, и когда сокет готов, вызывается предоставленное замыкание. Замыкание должно попытаться выполнить операцию ввода-вывода на сокете, вручную вызвав соответствующий системный вызов. Если операция завершается неудачно из-за того, что сокет фактически не готов, замыкание должно вернуть ошибку WouldBlock. В этом случае флаг готовности сбрасывается и готовность сокета ожидается снова. Этот цикл повторяется до тех пор, пока замыкание не вернет Ok или ошибку, отличную от WouldBlock.

Замыкание должно возвращать ошибку WouldBlock только в том случае, если оно выполнило операцию ввода-вывода на сокете, которая завершилась неудачей из-за неготовности сокета. Возврат ошибки WouldBlock в любой другой ситуации ошибочно сбросит флаг готовности, что может привести к некорректной работе сокета.

Замыкание не должно выполнять операцию ввода-вывода с использованием каких-либо методов, определенных для типа UdpSocket из Tokio, так как это нарушит работу флага готовности и может привести к некорректному поведению сокета.

Этот метод не предназначен для использования с комбинированными событиями интереса (interests). Замыкание должно выполнять только один тип операций ввода-вывода, поэтому оно не должно требовать более одного состояния готовности. Этот метод может вызвать панику или заблокироваться навсегда при вызове с комбинированным интересом.

Принимает одну датаграмму с подключенного адреса без удаления ее из очереди. В случае успеха возвращает количество прочитанных байтов.

Примечания

В Windows, если данные превышают размер указанного буфера, буфер заполняется первой частью данных, а peek возвращает ошибку WSAEMSGSIZE(10040). Лишние данные теряются. Всегда используйте буфер достаточного размера, способный вместить максимальный размер пакета UDP, который может достигать 65536 байт.

MacOS вернет ошибку, если передать буфер нулевого размера.

Если вас интересует только отправитель данных в начале очереди, попробуйте peek_sender.

Обратите внимание, что адресу сокета нельзя слепо доверять, поскольку отправить датаграмму UDP с поддельным адресом отправителя с помощью атаки внедрения пакетов относительно просто. Поскольку протокол UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола на уровне приложения.

Примеры

use tokio::net::UdpSocket;
use std::io;

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

Принимает данные с подключенного адреса без удаления их из очереди входящих сообщений.

Примечания

Обратите внимание, что при многократных вызовах метода poll_* в направлении recv только Waker из Context, переданного в последний вызов, будет запланирован для получения пробуждения.

В Windows, если данные превышают размер указанного буфера, буфер заполняется первой частью данных, а peek возвращает ошибку WSAEMSGSIZE(10040). Лишние данные теряются. Всегда используйте буфер достаточного размера, способный вместить максимальный размер пакета UDP, который может достигать 65536 байт.

MacOS вернет ошибку, если передать буфер нулевого размера.

Если вас интересует только отправитель данных в начале очереди, попробуйте poll_peek_sender.

Обратите внимание, что адресу сокета нельзя слепо доверять, поскольку отправить датаграмму UDP с поддельным адресом отправителя с помощью атаки внедрения пакетов относительно просто. Поскольку протокол UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола на уровне приложения.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если сокет не готов к чтению
• Poll::Ready(Ok(())) считывает данные в ReadBuf, если сокет готов
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, кроме WouldBlock.

Пытается принять данные с подключенного адреса без удаления их из очереди входящих сообщений. В случае успеха возвращает количество прочитанных байтов.

Когда нет ожидающих данных, возвращается Err(io::ErrorKind::WouldBlock). Эта функция обычно используется в паре с readable().

Примечания

В Windows, если данные превышают размер указанного буфера, буфер заполняется первой частью данных, а peek возвращает ошибку WSAEMSGSIZE(10040). Лишние данные теряются. Всегда используйте буфер достаточного размера, способный вместить максимальный размер пакета UDP, который может достигать 65536 байт.

MacOS вернет ошибку, если передать буфер нулевого размера.

Если вас интересует только отправитель данных в начале очереди, попробуйте try_peek_sender.

Обратите внимание, что адресу сокета нельзя слепо доверять, поскольку отправить датаграмму UDP с поддельным адресом отправителя с помощью атаки внедрения пакетов относительно просто. Поскольку протокол UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола на уровне приложения.

Получает данные из сокета без их удаления из очереди входящих сообщений. В случае успеха возвращает количество прочитанных байтов и адрес, откуда поступили данные.

Примечания

В Windows, если размер данных превышает указанный буфер, буфер заполняется первой частью данных, а peek_from возвращает ошибку WSAEMSGSIZE(10040). Оставшаяся часть данных теряется. Всегда используйте буфер достаточного размера, чтобы вместить максимальный размер UDP-пакета, который может достигать 65536 байт.

MacOS вернет ошибку, если передать буфер нулевого размера.

Если вас интересует только отправитель данных в начале очереди, используйте peek_sender.

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным источником при атаке внедрения пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола прикладного уровня.

Примеры

use tokio::net::UdpSocket;
use std::io;

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

Получает данные из сокета без их удаления из очереди входящих сообщений. В случае успеха возвращает адрес отправителя датаграммы.

Примечания

Обратите внимание, что при многократных вызовах метода poll_* в направлении recv только Waker из Context, переданного в самый последний вызов, будет запланирован на получение пробуждения

В Windows, если размер данных превышает указанный буфер, буфер заполняется первой частью данных, а peek возвращает ошибку WSAEMSGSIZE(10040). Оставшаяся часть данных теряется. Всегда используйте буфер достаточного размера, чтобы вместить максимальный размер UDP-пакета, который может достигать 65536 байт.

MacOS вернет ошибку, если передать буфер нулевого размера.

Если вас интересует только отправитель данных в начале очереди, используйте poll_peek_sender.

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным источником при атаке внедрения пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола прикладного уровня.

Возвращаемое значение

Функция возвращает:

• Poll::Pending если сокет не готов к чтению
• Poll::Ready(Ok(addr)) считывает данные из addr в ReadBuf если сокет готов
• Poll::Ready(Err(e)) если произошла ошибка.

Ошибки

Эта функция может возвращать любую стандартную ошибку ввода-вывода, кроме WouldBlock.

Пытается получить данные из сокета без их удаления из очереди входящих сообщений. В случае успеха возвращает количество прочитанных байтов и адрес отправителя датаграммы.

Если ожидающих данных нет, возвращается Err(io::ErrorKind::WouldBlock). Эта функция обычно используется в паре с readable().

Примечания

В Windows, если размер данных превышает указанный буфер, буфер заполняется первой частью данных, а peek возвращает ошибку WSAEMSGSIZE(10040). Оставшаяся часть данных теряется. Всегда используйте буфер достаточного размера, чтобы вместить максимальный размер UDP-пакета, который может достигать 65536 байт.

MacOS вернет ошибку, если передать буфер нулевого размера.

Если вас интересует только отправитель данных в начале очереди, используйте try_peek_sender.

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным источником при атаке внедрения пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола прикладного уровня.

Получает отправителя данных в начале очереди входящих сообщений, ожидая, если она пуста.

Это эквивалентно вызову peek_from с буфером нулевого размера, но подавляет ошибку WSAEMSGSIZE в Windows и ошибку «invalid argument» в macOS.

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным источником при атаке внедрения пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола прикладного уровня.

Получает отправителя данных в начале очереди входящих сообщений, планируя пробуждение, если она пуста.

Это эквивалентно вызову poll_peek_from с буфером нулевого размера, но подавляет ошибку WSAEMSGSIZE в Windows и ошибку «invalid argument» в macOS.

Примечания

Обратите внимание, что при многократных вызовах метода poll_* в направлении recv только Waker из Context, переданного в самый последний вызов, будет запланирован на получение пробуждения.

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным источником при атаке внедрения пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола прикладного уровня.

Пытается получить отправителя данных в начале очереди входящих сообщений.

Если ожидающих данных нет, возвращается Err(io::ErrorKind::WouldBlock). Эта функция обычно используется в паре с readable().

Обратите внимание, что адресу сокета нельзя безоговорочно доверять, так как отправить UDP-датаграмму с поддельным источником при атаке внедрения пакетов относительно просто. Поскольку UDP не сохраняет состояние и не проверяет источник пакета, злоумышленнику даже не нужно иметь возможность перехватывать трафик для вмешательства. Важно учитывать это при проектировании протокола прикладного уровня.

Возвращает значение опции SO_BROADCAST для этого сокета.

Для получения дополнительной информации об этой опции см. set_broadcast.

Устанавливает значение опции SO_BROADCAST для этого сокета.

Если включено, этому сокету разрешено отправлять пакеты на широковещательный адрес.

Возвращает значение опции IP_MULTICAST_LOOP для этого сокета.

Для получения дополнительной информации об этой опции см. set_multicast_loop_v4.

Устанавливает значение опции IP_MULTICAST_LOOP для этого сокета.

Если включено, многоадресные пакеты будут возвращаться обратно на локальный сокет.

Примечание

Это может не оказывать никакого эффекта на сокеты IPv6.

Получает значение опции IP_MULTICAST_TTL для этого сокета.

Для получения дополнительной информации об этой опции см. set_multicast_ttl_v4.

Устанавливает значение опции IP_MULTICAST_TTL для этого сокета.

Указывает значение времени жизни (TTL) исходящих многоадресных пакетов для этого сокета. Значение по умолчанию равно 1, что означает, что многоадресные пакеты не покидают локальную сеть, если явно не указано иное.

Примечание

Это может не оказывать никакого эффекта на сокеты IPv6.

Получает значение опции IPV6_MULTICAST_LOOP для этого сокета.

Для получения дополнительной информации об этой опции см. set_multicast_loop_v6.

Устанавливает значение опции IPV6_MULTICAST_LOOP для этого сокета.

Определяет, видит ли этот сокет многоадресные пакеты, которые он отправляет сам.

Примечание

Это может не оказывать никакого эффекта на сокеты IPv4.

Получает значение опции IPV6_TCLASS для этого сокета.

Для получения дополнительной информации об этой опции см. set_tclass_v6.

Устанавливает значение для опции IPV6_TCLASS на этом сокете.

Задаёт поле класса трафика, которое используется в каждом пакете, отправляемом из этого сокета.

Примечание

Это может не оказывать никакого эффекта на сокеты IPv4.

Получает значение опции IP_TTL для этого сокета.

Для получения дополнительной информации об этой опции см. set_ttl.

Примеры

use tokio::net::UdpSocket;

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

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

Устанавливает значение для опции IP_TTL на этом сокете.

Это значение задаёт поле времени жизни (TTL), которое используется в каждом пакете, отправляемом из этого сокета.

Примеры

use tokio::net::UdpSocket;

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

Получает значение опции IP_TOS для этого сокета.

Для получения дополнительной информации об этой опции см. set_tos_v4.

Устанавливает значение для опции IP_TOS на этом сокете.

Это значение задаёт поле типа обслуживания (type-of-service), которое используется в каждом пакете, отправляемом из этого сокета.

Примечание

• Это может не оказывать никакого эффекта на сокеты IPv6.
• В Windows IP_TOS поддерживается только в Windows 8+ или Windows Server 2012+.

Получает значение для опции SO_BINDTODEVICE на этом сокете

Это значение возвращает имя интерфейса устройства, к которому привязан сокет.

Устанавливает значение для опции SO_BINDTODEVICE на этом сокете

Если сокет привязан к интерфейсу, сокетом обрабатываются только пакеты, полученные от этого конкретного интерфейса. Обратите внимание, что это работает только для некоторых типов сокетов, в частности для сокетов AF_INET.

Если interface равен None или пустой строке, привязка удаляется.

Выполняет операцию типа IP_ADD_MEMBERSHIP.

Эта функция указывает новую многоадресную группу для присоединения этого сокета. Адрес должен быть допустимым адресом многоадресной рассылки, а interface — это адрес локального интерфейса, с помощью которого система должна присоединиться к многоадресной группе. Если он равен INADDR_ANY, подходящий интерфейс выбирается системой.

Выполняет операцию типа IPV6_ADD_MEMBERSHIP.

Эта функция указывает новую группу многоадресной рассылки, к которой должен присоединиться этот сокет. Адрес должен быть допустимым адресом многоадресной рассылки, а interface — это индекс интерфейса для присоединения/выхода (или 0 для указания любого интерфейса).

Выполняет операцию типа IP_DROP_MEMBERSHIP.

Для получения дополнительной информации об этой опции см. join_multicast_v4.

Выполняет операцию типа IPV6_DROP_MEMBERSHIP.

Для получения дополнительной информации об этой опции см. join_multicast_v6.

Возвращает значение опции SO_ERROR.

Примеры

use tokio::net::UdpSocket;
use std::io;

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

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

    Ok(())
}

Использует stream, возвращая объект ввода-вывода tokio.

Это эквивалентно UdpSocket::from_std(stream).

Возвращает аргумент без изменений.

Вызывает U::from(self).

То есть это преобразование делает всё, что определено в реализации From<T> for U.