Struct TorClientBuilder

pub struct TorClientBuilder<R: Runtime> { /* private fields */ }

An object for constructing a TorClient.

Returned by TorClient::builder().

Implementations

impl<R: Runtime> TorClientBuilder<R>

pub fn config(self, config: TorClientConfig) -> Self

Set the configuration for the TorClient under construction.

If not called, then a compiled-in default configuration will be used.

pub fn bootstrap_behavior(self, bootstrap_behavior: BootstrapBehavior) -> Self

Set the bootstrap behavior for the TorClient under construction.

If not called, then the default (BootstrapBehavior::OnDemand) will be used.

pub fn local_resource_timeout(self, timeout: Duration) -> Self

Set a timeout that we should allow when trying to acquire our local resources (including lock files.)

If no timeout is set, we wait for a short while (currently 500 msec) when invoked with create_bootstrapped or create_unbootstrapped_async, and we do not wait at all if invoked with create_unbootstrapped.

(This difference in default behavior is meant to avoid unintentional blocking. If you call this method, subsequent calls to crate_bootstrapped may block the current thread.)

The provided timeout value may not be larger than MAX_LOCAL_RESOURCE_TIMEOUT.

pub fn dirmgr_builder<B>(self, builder: Arc<dyn DirProviderBuilder<R>>) -> Self

where B: DirProviderBuilder<R> + 'static,

Available on crate features experimental-api and error_detail only.

Override the default function used to construct the directory provider.

Only available when compiled with the experimental-api feature: this code is unstable.

pub fn dirfilter<F>(self, filter: F) -> Self

where F: Into<Arc<dyn DirFilter + 'static>>,

Available on crate feature dirfilter only.

Install a DirFilter to

Only available when compiled with the dirfilter feature: this code is unstable and not recommended for production use.

pub fn create_unbootstrapped(&self) -> Result<TorClient<R>>

Create a TorClient from this builder, without automatically launching the bootstrap process.

If you have left the default BootstrapBehavior in place, the client will bootstrap itself as soon any attempt is made to use it. You can also bootstrap the client yourself by running its bootstrap() method.

If you have replaced the default behavior with BootstrapBehavior::Manual, any attempts to use the client will fail with an error of kind ErrorKind::BootstrapRequired, until you have called TorClient::bootstrap yourself. This option is useful if you wish to have control over the bootstrap process (for example, you might wish to avoid initiating network connections until explicit user confirmation is given).

If a local_resource_timeout has been set, this function may block the current thread. Use create_unbootstrapped_async if that is not what you want.

pub async fn create_unbootstrapped_async(&self) -> Result<TorClient<R>>

Like create_unbootstrapped, but does not block the thread while trying to acquire the lock.

If no local_resource_timeout has been set, this function may delay a short while (currently 500 msec) for local resources (such as lock files) to be available. Set local_resource_timeout to 0 if you do not want this behavior.

pub async fn create_bootstrapped(&self) -> Result<TorClient<R>>

Create a TorClient from this builder, and try to bootstrap it.

pub fn create_inert(&self) -> Result<InertTorClient>

Create an InertTorClient from this builder, without launching the bootstrap process, or connecting to the network.

It is currently unspecified whether constructing an InertTorClient will hold any locks that prevent opening a TorClient with the same directories.

Trait Implementations

impl<R: Clone + Runtime> Clone for TorClientBuilder<R>

fn clone(&self) -> TorClientBuilder<R>

Returns a copy of the value.

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

Performs copy-assignment from source.