Struct async_io::Async

pub struct Async<T> { /* fields omitted */ }

Async I/O.

This type converts a blocking I/O type into an async type, provided it is supported by epoll/kqueue/wepoll.

You can use predefined async methods on the standard networking types, or wrap blocking I/O operations in Async::read_with(), Async::read_with_mut(), Async::write_with(), and Async::write_with_mut().

NOTE: Do not use this type with File, Stdin, Stdout, or Stderr because they're not supported. Wrap them in blocking::Unblock instead.

Examples

To make an async I/O handle cloneable, wrap it in async_dup::Arc:

use async_dup::Arc;
use async_io::Async;
use futures_lite::io;
use std::net::TcpStream;

// Connect to a local server.
let stream = Async::<TcpStream>::connect(([127, 0, 0, 1], 8000)).await?;

// Create two handles to the stream.
let reader = Arc::new(stream);
let mut writer = reader.clone();

// Echo all messages from the read side of the stream into the write side.
io::copy(reader, &mut writer).await?;

If a type does but its reference doesn't implement AsyncRead and AsyncWrite, wrap it in async_dup::Mutex:

use async_dup::{Arc, Mutex};
use async_io::Async;
use futures_lite::{io, AsyncRead, AsyncWrite};
use std::net::TcpStream;

// Reads data from a stream and echoes it back.
async fn echo(stream: impl AsyncRead + AsyncWrite + Unpin) -> io::Result<u64> {
    let stream = Mutex::new(stream);

    // Create two handles to the stream.
    let reader = Arc::new(stream);
    let mut writer = reader.clone();

    // Echo all messages from the read side of the stream into the write side.
    io::copy(reader, &mut writer).await
}

// Connect to a local server and echo its messages back.
let stream = Async::<TcpStream>::connect(([127, 0, 0, 1], 8000)).await?;
echo(stream).await?;

Implementations

impl<T: AsRawSocket> Async<T>

pub fn new(io: T) -> Result<Async<T>>

Creates an async I/O handle.

This function will put the handle in non-blocking mode and register it in epoll on Linux/Android, kqueue on macOS/iOS/BSD, or wepoll on Windows. On Unix systems, the handle must implement AsRawFd, while on Windows it must implement AsRawSocket.

If the handle implements Read and Write, then Async<T> automatically implements AsyncRead and AsyncWrite. Other I/O operations can be asyncified by methods Async::read_with(), Async::read_with_mut(), Async::write_with(), and Async::write_with_mut().

NOTE: Do not use this type with File, Stdin, Stdout, or Stderr because they're not supported. Wrap them in blocking::Unblock instead.

Examples

use async_io::Async;
use std::net::{SocketAddr, TcpListener};

let listener = TcpListener::bind(SocketAddr::from(([127, 0, 0, 1], 0)))?;
let listener = Async::new(listener)?;

impl<T> Async<T>

pub fn get_ref(&self) -> &T

Gets a reference to the inner I/O handle.

Examples

use async_io::Async;
use std::net::TcpListener;

let listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 0))?;
let inner = listener.get_ref();

pub fn get_mut(&mut self) -> &mut T

Gets a mutable reference to the inner I/O handle.

Examples

use async_io::Async;
use std::net::TcpListener;

let mut listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 0))?;
let inner = listener.get_mut();

pub fn into_inner(self) -> Result<T>

Unwraps the inner non-blocking I/O handle.

Examples

use async_io::Async;
use std::net::TcpListener;

let listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 0))?;
let inner = listener.into_inner()?;

pub async fn readable<'_>(&'_ self) -> Result<()>

Waits until the I/O handle is readable.

This function completes when a read operation on this I/O handle wouldn't block.

Examples

use async_io::Async;
use std::net::TcpListener;

let mut listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 0))?;

// Wait until a client can be accepted.
listener.readable().await?;

pub async fn writable<'_>(&'_ self) -> Result<()>

Waits until the I/O handle is writable.

This function completes when a write operation on this I/O handle wouldn't block.

Examples

use async_io::Async;
use std::net::{TcpStream, ToSocketAddrs};

let addr = "example.com:80".to_socket_addrs()?.next().unwrap();
let stream = Async::<TcpStream>::connect(addr).await?;

// Wait until the stream is writable.
stream.writable().await?;

pub async fn read_with<R, '_>(
    &'_ self,
    op: impl FnMut(&T) -> Result<R>
) -> Result<R>

Performs a read operation asynchronously.

The I/O handle is registered in the reactor and put in non-blocking mode. This function invokes the op closure in a loop until it succeeds or returns an error other than io::ErrorKind::WouldBlock. In between iterations of the loop, it waits until the OS sends a notification that the I/O handle is readable.

The closure receives a shared reference to the I/O handle.

Examples

use async_io::Async;
use std::net::TcpListener;

let listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 0))?;

// Accept a new client asynchronously.
let (stream, addr) = listener.read_with(|l| l.accept()).await?;

pub async fn read_with_mut<R, '_>(
    &'_ mut self,
    op: impl FnMut(&mut T) -> Result<R>
) -> Result<R>

Performs a read operation asynchronously.

The I/O handle is registered in the reactor and put in non-blocking mode. This function invokes the op closure in a loop until it succeeds or returns an error other than io::ErrorKind::WouldBlock. In between iterations of the loop, it waits until the OS sends a notification that the I/O handle is readable.

The closure receives a mutable reference to the I/O handle.

Examples

use async_io::Async;
use std::net::TcpListener;

let mut listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 0))?;

// Accept a new client asynchronously.
let (stream, addr) = listener.read_with_mut(|l| l.accept()).await?;

pub async fn write_with<R, '_>(
    &'_ self,
    op: impl FnMut(&T) -> Result<R>
) -> Result<R>

Performs a write operation asynchronously.

The I/O handle is registered in the reactor and put in non-blocking mode. This function invokes the op closure in a loop until it succeeds or returns an error other than io::ErrorKind::WouldBlock. In between iterations of the loop, it waits until the OS sends a notification that the I/O handle is writable.

The closure receives a shared reference to the I/O handle.

Examples

use async_io::Async;
use std::net::UdpSocket;

let socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 8000))?;
socket.get_ref().connect("127.0.0.1:9000")?;

let msg = b"hello";
let len = socket.write_with(|s| s.send(msg)).await?;

pub async fn write_with_mut<R, '_>(
    &'_ mut self,
    op: impl FnMut(&mut T) -> Result<R>
) -> Result<R>

Performs a write operation asynchronously.

The I/O handle is registered in the reactor and put in non-blocking mode. This function invokes the op closure in a loop until it succeeds or returns an error other than io::ErrorKind::WouldBlock. In between iterations of the loop, it waits until the OS sends a notification that the I/O handle is writable.

The closure receives a mutable reference to the I/O handle.

Examples

use async_io::Async;
use std::net::UdpSocket;

let mut socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 8000))?;
socket.get_ref().connect("127.0.0.1:9000")?;

let msg = b"hello";
let len = socket.write_with_mut(|s| s.send(msg)).await?;

impl Async<TcpListener>

pub fn bind<A: Into<SocketAddr>>(addr: A) -> Result<Async<TcpListener>>

Creates a TCP listener bound to the specified address.

Binding with port number 0 will request an available port from the OS.

Examples

use async_io::Async;
use std::net::TcpListener;

let listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 0))?;
println!("Listening on {}", listener.get_ref().local_addr()?);

pub async fn accept<'_>(&'_ self) -> Result<(Async<TcpStream>, SocketAddr)>

Accepts a new incoming TCP connection.

When a connection is established, it will be returned as a TCP stream together with its remote address.

Examples

use async_io::Async;
use std::net::TcpListener;

let listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 8000))?;
let (stream, addr) = listener.accept().await?;
println!("Accepted client: {}", addr);

pub fn incoming(
    &self
) -> impl Stream<Item = Result<Async<TcpStream>>> + Send + Unpin + '_

Returns a stream of incoming TCP connections.

The stream is infinite, i.e. it never stops with a None.

Examples

use async_io::Async;
use futures_lite::stream::StreamExt;
use std::net::TcpListener;

let listener = Async::<TcpListener>::bind(([127, 0, 0, 1], 8000))?;
let mut incoming = listener.incoming();

while let Some(stream) = incoming.next().await {
    let stream = stream?;
    println!("Accepted client: {}", stream.get_ref().peer_addr()?);
}

impl Async<TcpStream>

pub async fn connect<A: Into<SocketAddr>>(addr: A) -> Result<Async<TcpStream>>

Creates a TCP connection to the specified address.

Examples

use async_io::Async;
use std::net::{TcpStream, ToSocketAddrs};

let addr = "example.com:80".to_socket_addrs()?.next().unwrap();
let stream = Async::<TcpStream>::connect(addr).await?;

pub async fn peek<'_, '_>(&'_ self, buf: &'_ mut [u8]) -> Result<usize>

Reads data from the stream without removing it from the buffer.

Returns the number of bytes read. Successive calls of this method read the same data.

Examples

use async_io::Async;
use futures_lite::{io::AsyncWriteExt, stream::StreamExt};
use std::net::{TcpStream, ToSocketAddrs};

let addr = "example.com:80".to_socket_addrs()?.next().unwrap();
let mut stream = Async::<TcpStream>::connect(addr).await?;

stream
    .write_all(b"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
    .await?;

let mut buf = [0u8; 1024];
let len = stream.peek(&mut buf).await?;

impl Async<UdpSocket>

pub fn bind<A: Into<SocketAddr>>(addr: A) -> Result<Async<UdpSocket>>

Creates a UDP socket bound to the specified address.

Binding with port number 0 will request an available port from the OS.

Examples

use async_io::Async;
use std::net::UdpSocket;

let socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 0))?;
println!("Bound to {}", socket.get_ref().local_addr()?);

pub async fn recv_from<'_, '_>(
    &'_ self,
    buf: &'_ mut [u8]
) -> Result<(usize, SocketAddr)>

Receives a single datagram message.

Returns the number of bytes read and the address the message came from.

This method must be called with a valid byte slice of sufficient size to hold the message. If the message is too long to fit, excess bytes may get discarded.

Examples

use async_io::Async;
use std::net::UdpSocket;

let socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 8000))?;

let mut buf = [0u8; 1024];
let (len, addr) = socket.recv_from(&mut buf).await?;

pub async fn peek_from<'_, '_>(
    &'_ self,
    buf: &'_ mut [u8]
) -> Result<(usize, SocketAddr)>

Receives a single datagram message without removing it from the queue.

Returns the number of bytes read and the address the message came from.

This method must be called with a valid byte slice of sufficient size to hold the message. If the message is too long to fit, excess bytes may get discarded.

Examples

use async_io::Async;
use std::net::UdpSocket;

let socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 8000))?;

let mut buf = [0u8; 1024];
let (len, addr) = socket.peek_from(&mut buf).await?;

pub async fn send_to<A: Into<SocketAddr>, '_, '_>(
    &'_ self,
    buf: &'_ [u8],
    addr: A
) -> Result<usize>

Sends data to the specified address.

Returns the number of bytes writen.

Examples

use async_io::Async;
use std::net::UdpSocket;

let socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 0))?;
let addr = socket.get_ref().local_addr()?;

let msg = b"hello";
let len = socket.send_to(msg, addr).await?;

pub async fn recv<'_, '_>(&'_ self, buf: &'_ mut [u8]) -> Result<usize>

Receives a single datagram message from the connected peer.

Returns the number of bytes read.

This method must be called with a valid byte slice of sufficient size to hold the message. If the message is too long to fit, excess bytes may get discarded.

The connect method connects this socket to a remote address. This method will fail if the socket is not connected.

Examples

use async_io::Async;
use std::net::UdpSocket;

let socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 8000))?;
socket.get_ref().connect("127.0.0.1:9000")?;

let mut buf = [0u8; 1024];
let len = socket.recv(&mut buf).await?;

pub async fn peek<'_, '_>(&'_ self, buf: &'_ mut [u8]) -> Result<usize>

Receives a single datagram message from the connected peer without removing it from the queue.

Returns the number of bytes read and the address the message came from.

This method must be called with a valid byte slice of sufficient size to hold the message. If the message is too long to fit, excess bytes may get discarded.

The connect method connects this socket to a remote address. This method will fail if the socket is not connected.

Examples

use async_io::Async;
use std::net::UdpSocket;

let socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 8000))?;
socket.get_ref().connect("127.0.0.1:9000")?;

let mut buf = [0u8; 1024];
let len = socket.peek(&mut buf).await?;

pub async fn send<'_, '_>(&'_ self, buf: &'_ [u8]) -> Result<usize>

Sends data to the connected peer.

Returns the number of bytes written.

The connect method connects this socket to a remote address. This method will fail if the socket is not connected.

Examples

use async_io::Async;
use std::net::UdpSocket;

let socket = Async::<UdpSocket>::bind(([127, 0, 0, 1], 8000))?;
socket.get_ref().connect("127.0.0.1:9000")?;

let msg = b"hello";
let len = socket.send(msg).await?;

Trait Implementations

impl<T: AsRawSocket> AsRawSocket for Async<T>

fn as_raw_socket(&self) -> RawSocket

Extracts the underlying raw socket from this object.

impl<T: Read> AsyncRead for Async<T>

fn poll_read(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &mut [u8]
) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &mut [IoSliceMut]
) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<T, '_> AsyncRead for &'_ Async<T> where
    &'a T: Read, 

fn poll_read(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &mut [u8]
) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &mut [IoSliceMut]
) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<T: Write> AsyncWrite for Async<T>

fn poll_write(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &[u8]
) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &[IoSlice]
) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, _: &mut Context) -> Poll<Result<()>>

Attempt to close the object.

impl<T, '_> AsyncWrite for &'_ Async<T> where
    &'a T: Write, 

fn poll_write(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &[u8]
) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &[IoSlice]
) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, _: &mut Context) -> Poll<Result<()>>

Attempt to close the object.

impl<T: Debug> Debug for Async<T>

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

Formats the value using the given formatter.

impl<T> Drop for Async<T>

fn drop(&mut self)

Executes the destructor for this type.