1. Project Overview & Quickstart (smol-rs/smol) Copy Chapter

smol

A small and fast async runtime.

This crate simply re-exports other smaller async crates (see the source).

To use tokio-based libraries with smol, apply the async-compat adapter to futures and I/O
types.

See the smol-macros crate if you want a no proc-macro, fast compiling, easy-to-use
async main and/or multi-threaded Executor setup out of the box.

Examples Copy Chapter

Connect to an HTTP website, make a GET request, and pipe the response to the standard output:

use smol::{io, net, prelude::*, Unblock};

fn main() -> io::Result<()> {
    smol::block_on(async {
        let mut stream = net::TcpStream::connect("example.com:80").await?;
        let req = b"GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n";
        stream.write_all(req).await?;

        let mut stdout = Unblock::new(std::io::stdout());
        io::copy(stream, &mut stdout).await?;
        Ok(())
    })
}

There's a lot more in the examples directory.

Subcrates Copy Chapter

• async-channel - Multi-producer multi-consumer channels
• async-executor - Composable async executors
• async-fs - Async filesystem primitives
• async-io - Async adapter for I/O types, also timers
• async-lock - Async locks (barrier, mutex, reader-writer lock, semaphore)
• async-net - Async networking primitives (TCP/UDP/Unix)
• async-process - Async interface for working with processes
• async-task - Task abstraction for building executors
• blocking - A thread pool for blocking I/O
• futures-lite - A lighter fork of futures
• polling - Portable interface to epoll, kqueue, event ports, and wepoll

TLS certificate Copy Chapter

Some code examples are using TLS for authentication. The repository
contains a self-signed certificate usable for testing, but it should not
be used for real-world scenarios. Browsers and tools like curl will
show this certificate as insecure.

In browsers, accept the security prompt or use curl -k on the
command line to bypass security warnings.

The certificate file was generated using
minica and
openssl:

minica --domains localhost -ip-addresses 127.0.0.1 -ca-cert certificate.pem
openssl pkcs12 -export -out identity.pfx -inkey localhost/key.pem -in localhost/cert.pem

Another useful tool for making certificates is mkcert.

MSRV Policy Copy Chapter

The Minimum Supported Rust Version (MSRV) of this crate is 1.85. As a tentative policy, the MSRV will not advance past the current Rust version provided by Debian Stable. At the time of writing, this version of Rust is 1.85. However, the MSRV may be advanced further in the event of a major ecosystem shift or a security vulnerability.

License Copy Chapter

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.

2. Official Technical Reference & Guides (smol-rs/async-io) Copy Chapter

async-io

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.