Runtime

tor_rtcompat

Trait Runtime 

Source 
pub trait Runtime:
    Sync
    + Send
    + Spawn
    + Blocking
    + Clone
    + SleepProvider
    + CoarseTimeProvider
    + NetStreamProvider<SocketAddr>
    + NetStreamProvider<SocketAddr>
    + TlsProvider<<Self as NetStreamProvider<SocketAddr>>::Stream>
    + UdpProvider
    + Debug
    + 'static { }
Expand description

A runtime for use by Tor client library code.

This trait comprises several other traits that we require all of our runtimes to provide:

  • futures::task::Spawn to launch new background tasks.
  • SleepProvider to pause a task for a given amount of time.
  • CoarseTimeProvider for a cheaper but less accurate notion of time.
  • NetStreamProvider to launch and accept network connections.
  • TlsProvider to launch TLS connections.
  • Blocking to be able to run synchronous (cpubound or IO) code, and re-enter the async context from synchronous thread (This may become optional in the future, if/when we add WASM support).

A value which is only Runtime cannot be used as an entry point to the runtime. For that, it must also implement ToplevelBlockOn, making it a ToplevelRuntime. Since you can only enter a runtime once, typically you use a ToplevelRuntime to enter the runtime, and use it as only a Runtime afterwards. This means that library code should typically deal with Runtime rather than ToplevelRuntime.

We require that every Runtime has an efficient Clone implementation that gives a new opaque reference to the same underlying runtime.

Additionally, every Runtime is Send and Sync, though these requirements may be somewhat relaxed in the future.

At some future point, Arti may require that the runtime impl<S> TlsProvider<S> (for suitableS), rather than just for their own TcpStreams. I.e., Arti may start to require that the runtime’s TLS provider can wrap any streams, not only the runtime’s own TCP streams. This might be expressed as an additional supertrait bound on Runtime, eg when Rust supports GATs, or as an additional bound on the Arti APIs that currently use Runtime. For API future compatibility, if you impl Runtime for MyRuntime, you should also ensure that you

ⓘ
impl<S> TlsProvider<S> for MyRuntime
where S: futures::AsyncRead + futures::AsyncWrite + Unpin + Send + 'static

Perhaps we will need this if we make our own TLS connections through Tor, rather than just channels to guards.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§