Структура Async

Источник: Документация smol::Async

#![allow(unused)]
fn main() {
pub struct Async<T> { /* private fields */ }
}

Асинхронный адаптер для I/O типов.

Этот тип переводит I/O дескриптор в неблокирующий режим, регистрирует его в epoll/kqueue/event ports/IOCP и предоставляет асинхронный интерфейс для работы с ним.

Особенности

Async является низкоуровневым примитивом и имеет некоторые ограничения:

Для более высокоуровневых примитивов, построенных на основе Async, используйте async-net или async-process (на Unix)
Небезопасно обращаться к внутреннему I/O источнику изменяемо с помощью этого примитива
Трейты AsyncRead и AsyncWrite не реализованы по умолчанию, если не гарантировано, что ресурс не будет инвалидирован при чтении или записи

Поддерживаемые типы

Async поддерживает все сетевые типы, а также некоторые OS-специфичные файловые дескрипторы, такие как timerfd и inotify.

Не используйте Async с типами типа File, Stdin, Stdout или Stderr, поскольку все операционные системы имеют проблемы с ними в неблокирующем режиме.

Конкурентный I/O

&Async<T> реализует AsyncRead и AsyncWrite, если &T реализует эти трейты, что означает, что задачи могут конкурентно читать и писать с использованием общих ссылок.

Важно: только одна задача может читать за раз и только одна задача может писать за раз. Допустимо иметь две задачи, где одна читает, а другая пишет одновременно, но недопустимо иметь две задачи, читающие одновременно или пишущие одновременно.

Закрытие

Закрытие стороны записи Async с помощью close() просто выполняет сброс. Если вы хотите завершить работу TCP или Unix сокета, используйте Shutdown.

Примеры

Подключение к серверу и возврат входящих сообщений обратно на сервер:

#![allow(unused)]
fn main() {
use async_io::Async;
use futures_lite::io;
use std::net::TcpStream;

// Подключаемся к локальному серверу.
let stream = Async::<TcpStream>::connect(([127, 0, 0, 1], 8000)).await?;

// Копируем все сообщения из стороны чтения потока в сторону записи.
io::copy(&stream, &stream).await?;
}

Реализации

Источник: Документация smol::Async

Конструкторы

Метод	Сигнатура	Описание
`new`	`pub fn new(io: T) -> Result<Async<T>>`	Создает новый асинхронный I/O дескриптор

Методы доступа

Метод	Сигнатура	Описание
`get_ref`	`pub fn get_ref(&self) -> &T`	Получает ссылку на внутренний дескриптор
`get_mut`	`pub fn get_mut(&mut self) -> &mut T`	Получает изменяемую ссылку на внутренний дескриптор
`into_inner`	`pub fn into_inner(self) -> Result<T>`	Извлекает внутренний дескриптор

Методы для чтения/записи

Метод	Сигнатура	Описание
`read_with`	`pub fn read_with<R>(&self, op: impl FnOnce(&T) -> Result<R>) -> impl Future<Output = Result<R>>`	Выполняет блокирующую операцию чтения асинхронно
`read_with_mut`	`pub fn read_with_mut<R>(&self, op: impl FnOnce(&mut T) -> Result<R>) -> impl Future<Output = Result<R>>`	Выполняет блокирующую операцию чтения с изменяемым доступом
`write_with`	`pub fn write_with<R>(&self, op: impl FnOnce(&T) -> Result<R>) -> impl Future<Output = Result<R>>`	Выполняет блокирующую операцию записи асинхронно
`write_with_mut`	`pub fn write_with_mut<R>(&self, op: impl FnOnce(&mut T) -> Result<R>) -> impl Future<Output = Result<R>>`	Выполняет блокирующую операцию записи с изменяемым доступом

Методы доступности

Метод	Сигнатура	Описание
`readable`	`pub fn readable(&self) -> Readable<'_, T>`	Создает фьючерс для ожидания доступности для чтения
`writable`	`pub fn writable(&self) -> Writable<'_, T>`	Создает фьючерс для ожидания доступности для записи
`poll_readable`	`pub fn poll_readable(&self, cx: &mut Context<'_>) -> Poll<Result<()>>`	Опрашивает доступность для чтения
`poll_writable`	`pub fn poll_writable(&self, cx: &mut Context<'_>) -> Poll<Result<()>>`	Опрашивает доступность для записи

Сетевые методы (для TcpStream)

Метод	Сигнатура	Описание
`connect`	`pub async fn connect(addr: impl ToSocketAddrs) -> Result<Async<TcpStream>>`	Асинхронно подключается к адресу
`peer_addr`	`pub fn peer_addr(&self) -> Result<SocketAddr>`	Возвращает адрес удаленного peer
`local_addr`	`pub fn local_addr(&self) -> Result<SocketAddr>`	Возвращает локальный адрес
`shutdown`	`pub fn shutdown(&self, how: Shutdown) -> Result<()>`	Завершает часть соединения

Сетевые методы (для TcpListener)

Метод	Сигнатура	Описание
`bind`	`pub fn bind(addr: impl ToSocketAddrs) -> Result<Async<TcpListener>>`	Привязывает сокет к адресу
`accept`	`pub async fn accept(&self) -> Result<(Async<TcpStream>, SocketAddr)>`	Асинхронно принимает входящее подключение
`local_addr`	`pub fn local_addr(&self) -> Result<SocketAddr>`	Возвращает локальный адрес

Сетевые методы (для UdpSocket)

Метод	Сигнатура	Описание
`bind`	`pub fn bind(addr: impl ToSocketAddrs) -> Result<Async<UdpSocket>>`	Привязывает UDP сокет к адресу
`connect`	`pub async fn connect(&self, addr: impl ToSocketAddrs) -> Result<()>`	Подключает UDP сокет к адресу
`send`	`pub async fn send(&self, buf: &[u8]) -> Result<usize>`	Отправляет данные в подключенный адрес
`recv`	`pub async fn recv(&self, buf: &mut [u8]) -> Result<usize>`	Получает данные из подключенного адреса
`send_to`	`pub async fn send_to(&self, buf: &[u8], addr: impl ToSocketAddrs) -> Result<usize>`	Отправляет данные на указанный адрес
`recv_from`	`pub async fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>`	Получает данные и адрес отправителя
`local_addr`	`pub fn local_addr(&self) -> Result<SocketAddr>`	Возвращает локальный адрес
`peer_addr`	`pub fn peer_addr(&self) -> Result<SocketAddr>`	Возвращает адрес удаленного peer

Трейты

Реализации From

Трейт	Описание
`From<Async<T>>`	Преобразование в внутренний тип

Реализации для трейтов асинхронного I/O

Трейт	Методы	Описание
`AsyncRead`	`poll_read`	Асинхронное чтение данных
`AsyncWrite`	`poll_write`, `poll_flush`, `poll_close`	Асинхронная запись данных
`AsyncBufRead`	`poll_fill_buf`, `consume`	Асинхронное буферизованное чтение
`AsyncSeek`	`poll_seek`	Асинхронное перемещение по потоку

Другие трейты

Трейт	Описание
`Debug`	Отладочное представление
`Clone`	Клонирование (если `T: Clone`)
`AsRef<T>`	Получение ссылки на внутренний тип
`AsMut<T>`	Получение изменяемой ссылки на внутренний тип

Зависимости

Структура Async зависит от следующих трейтов и типов:

std::io::Result, std::io::Error
std::net::ToSocketAddrs, SocketAddr
std::net::{TcpStream, TcpListener, UdpSocket}
std::future::Future
std::task::{Context, Poll}
futures_io::{AsyncRead, AsyncWrite, AsyncBufRead, AsyncSeek}
std::fmt::Debug
std::clone::Clone

Вспомогательные типы

Тип	Описание
`Readable<'a, T>`	Фьючерс для ожидания доступности чтения
`Writable<'a, T>`	Фьючерс для ожидания доступности записи

Keyboard shortcuts

DOCS.RS