daf5ecc153
Generated with the following commands: ``` cargo set-version --bump minor -p tor-cell cargo set-version --bump minor -p tor-linkspec cargo set-version --bump minor -p tor-proto cargo set-version --bump minor -p tor-netdoc cargo set-version --bump minor -p tor-circmgr cargo set-version --bump patch -p tor-cert cargo set-version --bump patch -p tor-basic-utils cargo set-version --bump patch -p tor-rpcbase cargo set-version --bump patch -p tor-llcrypto cargo set-version --bump patch -p tor-hscrypto cargo set-version --bump patch -p tor-checkable cargo set-version --bump patch -p tor-async-utils cargo set-version --bump patch -p caret cargo set-version --bump patch -p fs-mistrust cargo set-version --bump patch -p safelog cargo set-version --bump patch -p retry-error cargo set-version --bump patch -p tor-error cargo set-version --bump patch -p tor-config cargo set-version --bump patch -p tor-events cargo set-version --bump patch -p tor-units cargo set-version --bump patch -p tor-rtcompat cargo set-version --bump patch -p tor-rtmock cargo set-version --bump patch -p tor-protover cargo set-version --bump patch -p tor-bytes cargo set-version --bump patch -p tor-socksproto cargo set-version --bump patch -p tor-consdiff cargo set-version --bump patch -p tor-netdir cargo set-version --bump patch -p tor-congestion cargo set-version --bump patch -p tor-persist cargo set-version --bump patch -p tor-chanmgr cargo set-version --bump patch -p tor-ptmgr cargo set-version --bump patch -p tor-guardmgr cargo set-version --bump patch -p tor-dirclient cargo set-version --bump patch -p tor-dirmgr cargo set-version --bump patch -p tor-hsclient cargo set-version --bump patch -p tor-hsservice cargo set-version --bump patch -p arti-client cargo set-version --bump patch -p arti-rpcserver cargo set-version --bump patch -p arti-config cargo set-version --bump patch -p arti-hyper cargo set-version --bump patch -p arti cargo set-version --bump patch -p arti-bench cargo set-version --bump patch -p arti-testing ``` |
||
---|---|---|
.. | ||
misc | ||
src | ||
test-data-generator | ||
Cargo.toml | ||
README.md |
README.md
tor-rtcompat
Compatibility between different async runtimes for Arti.
Overview
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.
The [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.
Additionally, the AsyncRead
and AsyncWrite
traits provide by
[futures
] are not the same as those provided by tokio
, and
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 tokio
and async-std
runtimes. In the future we hope to add support
for other runtimes as needed.
This crate is part of Arti, a project to implement Tor in Rust. As such, it does not currently include (or plan to include) any functionality beyond what Arti needs to implement Tor.
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.
Using tor-rtcompat
The tor-rtcompat
crate provides several traits that
encapsulate different runtime capabilities.
- A runtime is a [
BlockOn
] if it can block on a future. - A runtime is a [
SleepProvider
] if it can make timer futures that become Ready after a given interval of time. - A runtime is a [
TcpProvider
] if it can make and receive TCP connections - A runtime is a [
TlsProvider
] if it can make TLS connections.
For convenience, the [Runtime
] trait derives from all the traits
above, plus [futures::task::Spawn
] and [Send
].
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 [Runtime
] with [PreferredRuntime::current()
]. -
If you want to construct a default runtime that you won't be using for anything besides Arti, you can use [
PreferredRuntime::create()
].
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 [
async_std::AsyncStdNativeTlsRuntime
], [async_std::AsyncStdRustlsRuntime
], [tokio::TokioNativeTlsRuntime
], or [tokio::TokioRustlsRuntime
]. To construct one of these runtimes, call itscreate()
method. Or if you have already constructed a Tokio runtime that you want to use, you can wrap it as a [Runtime
] explicitly withcurrent()
.
Advanced usage: implementing runtimes yourself
You might want to implement some of the traits above (especially [TcpProvider
] and
[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.
This can be more easily accomplished using the [CompoundRuntime
] type, which lets you
create a [Runtime
] from various implementors of the various traits (which don't all need to
be the same).
See arti-client/examples/hook-tcp.rs
for a full example of this.
Cargo features
Features supported by this crate:
tokio
-- build with Tokio supportasync-std
-- build with async-std supportnative-tls
-- build with the native-tls crate for TLS supportstatic
-- link the native TLS library statically (enables thevendored
feature of thenative-tls
crate).rustls
-- build with the rustls crate for TLS support. Note thatrustls
uses thering
crate, 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 tokio
and native-tls
in
its default configuration.
Design FAQ
Why support async_std
?
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.
Why a Runtime
trait, and not a set of functions?
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 block_on
function.
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 [Runtime
]s. 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.)
License: MIT OR Apache-2.0