Compatibility between different async runtimes for Arti.
Rust’s support for asynchronous programming is powerful, but still a bit immature: there are multiple powerful runtimes you can use, but they do not expose a consistent set of interfaces.
futures API abstracts much of the differences among these
runtime libraries, but there are still areas where no standard API
yet exists, including:
- Network programming.
- Time and delays.
- Launching new tasks
- Blocking until a task is finished.
AsyncWrite traits provide by
futures are not the same as those provided by
require compatibility wrappers to use.
To solve these problems, the
tor-rtcompat crate provides a set
of traits that represent a runtime’s ability to perform these
tasks, along with implementations for these traits for the
async-std runtimes. In the future we hope to add support
for other runtimes as needed.
We hope that in the future this crate can be replaced (or mostly replaced) with standardized and general-purpose versions of the traits it provides.
tor-rtcompat crate provides several traits that
encapsulate different runtime capabilities.
- A runtime is a
BlockOnif it can block on a future.
- A runtime is a
SleepProviderif it can make timer futures that become Ready after a given interval of time.
- A runtime is a
TcpProviderif it can make and receive TCP connections
- A runtime is a
TlsProviderif it can make TLS connections.
You can get a
Runtime in several ways:
If you already have an asynchronous backend (for example, one that you built with tokio by running with
#[tokio::main]), you can wrap it as a
If you want to construct a default runtime that you won’t be using for anything besides Arti, you can use [
Both of the above methods use the “preferred runtime”, which is usually Tokio.
However, changing the set of Cargo features available can affect this; see
PreferredRuntime] for more.
- If you want to use a runtime with an explicitly chosen backend,
name its type directly as [
tokio::TokioNativeTlsRuntime], or [
tokio::TokioRustlsRuntime]. To construct one of these runtimes, call its
create()method. Or if you have already constructed a Tokio runtime that you want to use, you can wrap it as a
You might want to implement some of the traits above (especially
TlsProvider) if you’re embedding Arti, and want more control over the resources it uses.
For example, you might want to perform actions when TCP connections open and close, replace the
TLS stack with your own, or proxy TCP connections over your own custom transport.
for a full example of this.
Features supported by this crate:
tokio– build with Tokio support
async-std– build with async-std support
native-tls– build with the native-tls crate for TLS support
static– link the native TLS library statically (enables the
vendoredfeature of the
rustls– build with the rustls crate for TLS support. Note that
ringcrate, which uses the old (3BSD/SSLEay) OpenSSL license, which may introduce licensing compatibility issues.
By default, this crate doesn’t enable any features. However, you’re almost certainly
using this as part of the
arti-client crate, which will enable
its default configuration.
Although Tokio currently a more popular and widely supported
asynchronous runtime than
async_std is, we believe that it’s
critical to build Arti against multiple runtimes.
By supporting multiple runtimes, we avoid making tokio-specific assumptions in our code, which we hope will make it easier to port to other environments (like WASM) in the future.
We could simplify this code significantly by removing most of the
traits it exposes, and instead just exposing a single
implementation. For example, instead of exposing a
BlockOn trait to represent blocking until a task is
done, we could just provide a single global
That simplification would come at a cost, however. First of all, it would make it harder for us to use Rust’s “feature” system correctly. Current features are supposed to be additive only, but if had a single global runtime, then support for different backends would be mutually exclusive. (That is, you couldn’t have both the tokio and async-std features building at the same time.)
Secondly, much of our testing in the rest of Arti relies on the
ability to replace
Runtimes. By treating a runtime as an
object, we can override a runtime’s view of time, or of the
network, in order to test asynchronous code effectively.
(See the [
tor-rtmock] crate for examples.)
Utilities for dealing with periodic recurring tasks.
Functions for task management that don’t belong inside the Runtime trait.
Traits used to describe TLS connections and objects that can create them.
A runtime made of several parts, each of which implements one trait-group.
An error value given when a function times out.
Trait for a runtime that can block on a future.
An object with a peer certificate: typically a TLS connection.
A runtime that we can use to run Tor as a client.
Trait for a runtime that can wait until a timer has expired.
Trait for a local socket that accepts incoming TCP streams.
Trait for a runtime that can create and accept TCP connections.
Trait for a runtime that knows how to create TLS connections over
TCP streams of type
Trait for a runtime that can send and receive UDP datagrams.
Trait for a localy bound Udp socket that can send and receive datagrams.