Struct ClientShared 

struct ClientShared<R: Runtime> {

    runtime: R,
    inner: Mutex<Inner<R>>,
    memquota: Arc<MemoryQuotaTracker>,
    inert_client: InertTorClient,
    state_directory: StateDirectory,
    statemgr: FsStateMgr,
    dirmgr_store: DirMgrStore<R>,
    addrcfg: MutCfg<ClientAddrConfig>,
    timeoutcfg: MutCfg<StreamTimeoutConfig>,
    reconfigure_lock: Arc<Mutex<()>>,
    status_receiver: BootstrapEvents,
    bootstrap_in_progress: Mutex<()>,
    bootstrap_setting_sender: Mutex<Sender<BootstrapSetting>>,
    should_bootstrap: BootstrapBehavior,
    dormant: Mutex<DropNotifyWatchSender<Option<DormantMode>>>,
    path_resolver: Arc<CfgPathResolver>,
}

Shared pieces of a TorClient, used to implement client functionality.

In the future, we might choose to expose this along with APIs.

Fields

runtime: R

Asynchronous runtime object.

inner: Mutex<Inner<R>>

Inner typestate object to represent the parts of the ClientShared that may be absent depending on whether we are running.

memquota: Arc<MemoryQuotaTracker>

Memory quota tracker

inert_client: InertTorClient

A handle to this client’s InertTorClient.

Used for accessing the key manager and other persistent state.

state_directory: StateDirectory

Location on disk where we store persistent data containing both location and Mistrust information.

This path is configured via [storage] in the config but is not used directly as a StateDirectory in most places. Instead, its path and Mistrust information are copied to subsystems like dirmgr, keymgr, and statemgr during TorClient creation.

statemgr: FsStateMgr

Location on disk where we store persistent data (cooked state manager).

dirmgr_store: DirMgrStore<R>

Directory manager persistent storage.

addrcfg: MutCfg<ClientAddrConfig>

Client address configuration

timeoutcfg: MutCfg<StreamTimeoutConfig>

Client DNS configuration

reconfigure_lock: Arc<Mutex<()>>

Mutex used to serialize concurrent attempts to reconfigure a TorClient.

See TorClient::reconfigure for more information on its use.

status_receiver: BootstrapEvents

A stream of bootstrap messages that we can clone when a client asks for it.

(We don’t need to observe this stream ourselves, since it drops each unobserved status change when the next status change occurs.)

bootstrap_in_progress: Mutex<()>

mutex used to prevent two tasks from trying to bootstrap at once.

bootstrap_setting_sender: Mutex<Sender<BootstrapSetting>>

Sender used to update changes in our bootstrap settings.

should_bootstrap: BootstrapBehavior

Whether or not we should call bootstrap before doing things that require bootstrapping.

If this is BootstrapBehavior::OnDemand, we wait for the client to bootstrap (launching a bootstrap if necessary) before performing any operation that needs circuits. If this is BootstrapBehavior::Manual, we give an error if we are told to do something that needs circuits and we have not been told to bootstrap.

dormant: Mutex<DropNotifyWatchSender<Option<DormantMode>>>

Shared boolean for whether we’re currently in “dormant mode” or not.

path_resolver: Arc<CfgPathResolver>

The path resolver given to us by a TorClientConfig.

We must not add our own variables to it since TorClientConfig uses it to perform its own path expansions. If we added our own variables, it would introduce an inconsistency where paths expanded by the TorClientConfig would expand differently than when expanded by us.

Implementations

impl<R: Runtime> ClientShared<R>

fn instantiate_running_inner( &self, inner_guard: MutexGuard<'_, Inner<R>>, ) -> Result<Arc<RunningInner<R>>, ErrorDetail>

Used by bootstrap_inner: Return a RunningInner, constructing it if necessary.

async fn bootstrap_inner(&self) -> StdResult<(), ErrorDetail>

Implementation of bootstrap, split out in order to avoid manually specifying double error conversions.

async fn wait_for_bootstrap_running( &self, action: &'static str, ) -> StdResult<Arc<RunningInner<R>>, ErrorDetail>

Ensure that this client is running and bootstrapped, and return a RunningInner if it is.

If we’re not bootstrapped, we either try to bootstrap or return an error, depending on self.should_bootstrap:

For BootstrapBehavior::OnDemand clients

Initiate a bootstrap by calling bootstrap_inner (which is idempotent, so attempts to bootstrap twice will just do nothing).

For BootstrapBehavior::Manual clients

Check whether a bootstrap is in progress; if one is, wait until it finishes. Then see whether we’re bootstrapped, and return either a success or a failure.

fn running_inner( &self, action: &'static str, ) -> StdResult<Arc<RunningInner<R>>, ErrorDetail>

If we are currently bootstrapping or running, return a RunningInner.

fn initiate_bootstrap_if_needed( &self, action: &'static str, ) -> StdResult<Arc<RunningInner<R>>, ErrorDetail>

Ensure that our bootstrap state is RunningInner, if possible.

Return an error if our BootstrapBehavior is Manual and have not created a RunningInner.

fn reconfigure_inner( &self, new_config: &TorClientConfig, how: Reconfigure, _reconfigure_lock_guard: &MutexGuard<'_, ()>, ) -> Result<()>

This is split out from reconfigure so we can do the all-or-nothing check without recursion. the caller to this method must hold the reconfigure_lock.