58 releases (38 stable)

2.4.0 Nov 7, 2024
2.3.3 Jun 1, 2024
2.3.2 Mar 10, 2024
2.2.2 Dec 11, 2023
0.1.0 May 18, 2019

#8 in Asynchronous

Download history 439017/week @ 2024-12-27 802932/week @ 2025-01-03 958929/week @ 2025-01-10 859915/week @ 2025-01-17 905106/week @ 2025-01-24 972725/week @ 2025-01-31 1092075/week @ 2025-02-07 1034926/week @ 2025-02-14 1140971/week @ 2025-02-21 1153304/week @ 2025-02-28 1203713/week @ 2025-03-07 1317124/week @ 2025-03-14 2117525/week @ 2025-03-21 1326371/week @ 2025-03-28 1377903/week @ 2025-04-04 1179516/week @ 2025-04-11

6,300,422 downloads per month
Used in 4,371 crates (251 directly)

Apache-2.0 OR MIT

145KB
2K SLoC

async-io

Build License Cargo Documentation

Async I/O and timers.

This crate provides two tools:

  • Async, an adapter for standard networking types (and many other types) to use in async programs.
  • Timer, a future that expires at a point in time.

For concrete async networking types built on top of this crate, see async-net.

Implementation

The first time Async or Timer is used, a thread named "async-io" will be spawned. The purpose of this thread is to wait for I/O events reported by the operating system, and then wake appropriate futures blocked on I/O or timers when they can be resumed.

To wait for the next I/O event, the "async-io" thread uses epoll on Linux/Android/illumos, kqueue on macOS/iOS/BSD, event ports on illumos/Solaris, and IOCP on Windows. That functionality is provided by the polling crate.

However, note that you can also process I/O events and wake futures on any thread using the block_on() function. The "async-io" thread is therefore just a fallback mechanism processing I/O events in case no other threads are.

Examples

Connect to example.com:80, or time out after 10 seconds.

use async_io::{Async, Timer};
use futures_lite::{future::FutureExt, io};

use std::net::{TcpStream, ToSocketAddrs};
use std::time::Duration;

let addr = "example.com:80".to_socket_addrs()?.next().unwrap();

let stream = Async::<TcpStream>::connect(addr).or(async {
    Timer::after(Duration::from_secs(10)).await;
    Err(io::ErrorKind::TimedOut.into())
})
.await?;

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~3–13MB
~174K SLoC