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
!Sendfutures. - 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.