Expand description
§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
ToplevelBlockOn
if it can block on a top-level 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
CoarseTimeProvider
if it provides a monotonic clock which is fast to query, but perhaps has lower-precision or lower-accuracy. - A runtime is a
NetStreamProvider
<std::net::SocketAddr>
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 aRuntime
withPreferredRuntime::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
, ortokio::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 aRuntime
explicitly withcurrent()
.
§fork
on Unix, threads, and Rust
Rust is typically not sound in combination with fork
.
This is mostly because
(i) if there are any other threads in the program,
the environment after fork
(but before any exec
)
is extremely restricted and hazardous, and
(ii) Rust code is allowed to make threads, and often does so.
For this reason, Rust fork
APIs are always unsafe
.
Most async runtimes create threads. Therefore, for example, Tokio doesn’t work if you fork.
Therefore:
§Do not fork
after creating any Runtime
After instantiating any Runtime
, you must not fork.
This restriction applies to the whole process, and applies
to forking from Rust, from C, or from any other language.
You may not fork even after that Runtime
value has been dropped or shut down.
You may use safe facilities like std::process::Command
and tokio::process::Command
.
You may also use C libraries (and facilities in other languages)
that wrap up fork/exec,
so long as those facilities are safe to use in the presence of multiple threads
(even threads that the other language doesn’t know about).
You may fork and then exec, or fork and then _exit
,
but the execution environment between between fork and exec/_exit
is extremely restrictive.
std::os::unix::process::CommandExt::pre_exec
has a summary.
Runtime
s for which fork without exec is permitted,
will document that explicitly.
§Advanced usage: implementing runtimes yourself
You might want to implement some of the traits above (especially NetStreamProvider
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
ToplevelBlockOn
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
Modules§
- async_
std ( native-tls
orrustls
) andasync-std
- Entry points for use with async_std runtimes.
- coarse_
time 🔒 - Wrapper for coarsetime.
- compound 🔒
- Define a
CompoundRuntime
part that can be built from several component pieces. - dyn_
time 🔒 - type-erased time provider
- general
- Support for streams and listeners on
general::SocketAddr
. - impls 🔒
( native-tls
orrustls
) and (async-std
ortokio
) - Different implementations of a common async API for use in arti
- opaque 🔒
- Declare a macro for making opaque runtime wrappers.
- scheduler
- Utilities for dealing with periodic recurring tasks.
- task
- Functions for task management that don’t belong inside the Runtime trait.
- timer 🔒
- Definitions for
SleepProviderExt
and related types. - tls
- Traits used to describe TLS connections and objects that can create them.
- tokio
( native-tls
orrustls
) andtokio
- Entry points for use with Tokio runtimes.
- traits 🔒
- Declarations for traits that we need our runtimes to implement.
- unimpl
- Implementations for unsupported stream and listener types.
- unix
- Functionality for working with AF_UNIX addresses.
Macros§
- declare_
conditional_ 🔒macro - Helper: define a macro that expands a token tree iff a pair of features are both present.
- test_
with_ all_ runtimes ( native-tls
orrustls
) and (tokio
orasync-std
) - Run a test closure, passing as argument every supported runtime.
- test_
with_ one_ runtime ( native-tls
orrustls
) and (tokio
orasync-std
) - Run a test closure, passing as argument one supported runtime.
Structs§
- Coarse
Duration - A duration with reduced precision, and, in the future, saturating arithmetic
- Coarse
Instant - A monotonic timestamp with reduced precision, and, in the future, saturating arithmetic
- Compound
Runtime - A runtime made of several parts, each of which implements one trait-group.
- DynTime
Provider - Type-erased
SleepProvider
andCoarseTimeProvider
- NoOp
Stream OpsHandle - A
StreamOps
handle that always returns an error. - Preferred
Runtime ( native-tls
orrustls
) and (async-std
ortokio
) - The runtime that we prefer to use, out of all the runtimes compiled into the tor-rtcompat crate.
- Real
Coarse Time Provider - Provider of reduced-precision timestamps using the real OS clock
- Timeout
- A timeout returned by
SleepProviderExt::timeout
. - Timeout
Error - An error value given when a function times out.
- Unsupported
Stream Op - Error: Tried to perform a
StreamOps
operation on an unsupported stream type or on an unsupported platform.
Traits§
- Blocking
- Support for interacting with blocking (non-async) code
- Certified
Conn - An object with a peer certificate: typically a TLS connection.
- Coarse
Time Provider - A provider of reduced-precision timestamps
- NetStream
Listener - Trait for a local socket that accepts incoming streams.
- NetStream
Provider - Trait for a runtime that can create and accept connections over network sockets.
- Runtime
- A runtime for use by Tor client library code.
- Runtime
Subst Ext - Extension trait on Runtime: Construct new Runtimes that replace part of an original runtime.
- Sleep
Provider - Trait for a runtime that can wait until a timer has expired.
- Sleep
Provider Ext - An extension trait on
SleepProvider
for timeouts and clock delays. - Stream
Ops - Trait providing additional operations on network sockets.
- TlsProvider
- Trait for a runtime that knows how to create TLS connections over
TCP streams of type
S
. - Toplevel
Block On - Trait for a runtime that can be entered to block on a toplevel future.
- Toplevel
Runtime - A runtime that we can use to run Tor as a client.
- UdpProvider
- Trait for a runtime that can send and receive UDP datagrams.
- UdpSocket
- Trait for a locally bound Udp socket that can send and receive datagrams.