Struct PreferredRuntime

pub struct PreferredRuntime { /* private fields */ }

Available on (crate features native-tls or rustls) and (crate features async-std or tokio) only.

The runtime that we prefer to use, out of all the runtimes compiled into the tor-rtcompat crate.

If tokio and async-std are both available, we prefer tokio for its performance. If native_tls and rustls are both available, we prefer native_tls since it has been used in Arti for longer.

The process may not fork (except, very carefully, before exec) after creating this or any other Runtime.

Implementations

impl PreferredRuntime

pub fn current() -> Result<Self>

Obtain a PreferredRuntime from the currently running asynchronous runtime. Generally, this is what you want.

This tries to get a handle to a currently running asynchronous runtime, and wraps it; the returned PreferredRuntime isn’t the same thing as the asynchronous runtime object itself (e.g. tokio::runtime::Runtime).

Panics

When tor-rtcompat is compiled with the tokio feature enabled (regardless of whether the async-std feature is also enabled), panics if called outside of Tokio runtime context. See tokio::runtime::Handle::current.

Usage notes

Once you have a runtime returned by this function, you should just create more handles to it via Clone.

Limitations

If the tor-rtcompat crate was compiled with tokio support, this function will never return a runtime based on async_std.

The process may not fork (except, very carefully, before exec) after creating this or any other Runtime.

pub fn create() -> Result<Self>

Create and return a new instance of the default Runtime.

Generally you should call this function at most once, and then use Clone::clone() to create additional references to that runtime.

Tokio users may want to avoid this function and instead obtain a runtime using PreferredRuntime::current: this function always builds a runtime, and if you already have a runtime, that isn’t what you want with Tokio.

If you need more fine-grained control over a runtime, you can create it using an appropriate builder type or function.

The process may not fork (except, very carefully, before exec) after creating this or any other Runtime.

Trait Implementations

impl Blocking for PreferredRuntime

type ThreadHandle<T: Send + 'static> = <TokioNativeTlsRuntime as Blocking>::ThreadHandle<T>

Future from spawn_blocking

fn spawn_blocking<F, T>( &self, f: F, ) -> <PreferredRuntime as Blocking>::ThreadHandle<T>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Spawn a thread for blocking IO or CPU-bound work.

fn reenter_block_on<F>(&self, future: F) -> F::Output

where F: Future, F::Output: Send + 'static,

Block on a future, from within Blocking::spawn_blocking

fn blocking_io<F, T>(&self, f: F) -> impl Future<Output = T>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Perform some blocking IO from an async future

impl Clone for PreferredRuntime

fn clone(&self) -> PreferredRuntime

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CoarseTimeProvider for PreferredRuntime

fn now_coarse(&self) -> CoarseInstant

Return the CoarseTimeProvider’s view of the current instant.

impl Debug for PreferredRuntime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl NetStreamProvider<SocketAddr> for PreferredRuntime

type Stream = <TokioNativeTlsRuntime as NetStreamProvider<SocketAddr>>::Stream

The type for the connections returned by Self::connect().

type Listener = <TokioNativeTlsRuntime as NetStreamProvider<SocketAddr>>::Listener

The type for the listeners returned by Self::listen().

fn connect<'life0, 'life1, 'async_trait>( &'life0 self, addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = Result<Self::Stream>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Launch a connection connection to a given socket address.

fn listen<'life0, 'life1, 'async_trait>( &'life0 self, addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = Result<Self::Listener>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Open a listener on a given socket address.

impl NetStreamProvider for PreferredRuntime

type Stream = <TokioNativeTlsRuntime as NetStreamProvider>::Stream

The type for the connections returned by Self::connect().

type Listener = <TokioNativeTlsRuntime as NetStreamProvider>::Listener

The type for the listeners returned by Self::listen().

fn connect<'life0, 'life1, 'async_trait>( &'life0 self, addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = Result<Self::Stream>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Launch a connection connection to a given socket address.

fn listen<'life0, 'life1, 'async_trait>( &'life0 self, addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = Result<Self::Listener>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Open a listener on a given socket address.

impl SleepProvider for PreferredRuntime

type SleepFuture = <TokioNativeTlsRuntime as SleepProvider>::SleepFuture

A future returned by SleepProvider::sleep()

fn sleep(&self, duration: Duration) -> Self::SleepFuture

Return a future that will be ready after duration has elapsed.

fn now(&self) -> Instant

Return the SleepProvider’s view of the current instant.

fn wallclock(&self) -> SystemTime

Return the SleepProvider’s view of the current wall-clock time.

fn block_advance<T: Into<String>>(&self, _reason: T)

Signify that a test running under mock time shouldn’t advance time yet, with a given unique reason string. This is useful for making sure (mock) time doesn’t advance while things that might require some (real-world) time to complete do so, such as spawning a task on another thread.

fn release_advance<T: Into<String>>(&self, _reason: T)

Signify that the reason to withhold time advancing provided in a call to block_advance no longer exists, and it’s fine to move time forward if nothing else is blocking advances.

fn allow_one_advance(&self, _dur: Duration)

Allow a test running under mock time to advance time by the provided duration, even if the above block_advance API has been used.

impl Spawn for PreferredRuntime

fn spawn_obj(&self, future: FutureObj<'static, ()>) -> Result<(), SpawnError>

Spawns a future that will be run to completion.

fn status(&self) -> Result<(), SpawnError>

Determines whether the executor is able to spawn new tasks.

impl<S> TlsProvider<S> for PreferredRuntime

where S: AsyncRead + AsyncWrite + StreamOps + Unpin + Send + 'static,

type Connector = <TokioNativeTlsRuntime as TlsProvider<S>>::Connector

The Connector object that this provider can return.

type TlsStream = <TokioNativeTlsRuntime as TlsProvider<S>>::TlsStream

The type of the stream returned by that connector.

fn tls_connector(&self) -> Self::Connector

Return a TLS connector for use with this runtime.

fn supports_keying_material_export(&self) -> bool

Return true iff the keying material exporters (RFC 5705) is supported.

impl ToplevelBlockOn for PreferredRuntime

fn block_on<F: Future>(&self, future: F) -> F::Output

Run future until it is ready, and return its output.

impl UdpProvider for PreferredRuntime

type UdpSocket = <TokioNativeTlsRuntime as UdpProvider>::UdpSocket

The type of Udp Socket returned by Self::bind()

fn bind<'life0, 'life1, 'async_trait>( &'life0 self, addr: &'life1 SocketAddr, ) -> Pin<Box<dyn Future<Output = Result<Self::UdpSocket>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Bind a local port to send and receive packets from