smol

A small and fast async runtime for Rust.

This runtime extends the standard library with async combinators and is only 1500 lines of code long.

Reading the docs or looking at the examples is a great way to start learning async Rust.

Async I/O is implemented using epoll on Linux/Android, kqueue on macOS/iOS/BSD, and wepoll on Windows.

What makes smol different from async-std and tokio? Read this blog post.

Features

Async TCP, UDP, Unix domain sockets, and custom file descriptors.
Thread-local executor for !Send futures.
Work-stealing executor that adapts to uneven workloads.
Blocking executor for files, processes, and standard I/O.
Tasks that support cancellation.
Userspace timers.

Examples

You need to be in the examples directory to run them:

$ cd examples
$ ls
$ cargo run --example ctrl-c

Compatibility

See this example for how to use smol with async-std, tokio, surf, and reqwest.

There is an optional feature for seamless integration with crates depending on tokio. It creates a global tokio runtime and sets up its context inside smol. Enable the feature as follows:

[dependencies]
smol = { version = "0.1", features = ["tokio02"] }

Documentation

You can read the docs here, or generate them on your own.

If you'd like to explore the implementation in more depth, the following command generates docs for the whole crate, including private modules:

cargo doc --document-private-items --no-deps --open

Other crates

My personal crate recommendation list:

Channels, pipes, and mutexes: piper
HTTP clients: surf, isahc, reqwest
HTTP servers: async-h1, hyper
WebSockets: async-tungstenite
TLS authentication: async-native-tls
Signals: ctrlc, signal-hook

TLS certificate

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

License

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.

spinda/smol