Struct tor_circmgr::CircMgr

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

A Circuit Manager (CircMgr) manages a set of circuits, returning them when they’re suitable, and launching them if they don’t already exist.

Right now, its notion of “suitable” is quite rudimentary: it just believes in two kinds of circuits: Exit circuits, and directory circuits. Exit circuits are ones that were created to connect to a set of ports; directory circuits were made to talk to directory caches.

This is a “handle”; clones of it share state.

Implementations

impl<R: Runtime> CircMgr<R>

pub fn new<SM, CFG: CircMgrConfig>( config: &CFG, storage: SM, runtime: &R, chanmgr: Arc<ChanMgr<R>>, guardmgr: GuardMgr<R> ) -> Result<Arc<Self>>

where SM: StateMgr + Clone + Send + Sync + 'static,

Construct a new circuit manager.

Usage note

For the manager to work properly, you will need to call CircMgr::launch_background_tasks.

pub fn launch_background_tasks<D>( self: &Arc<Self>, runtime: &R, dir_provider: &Arc<D>, state_mgr: FsStateMgr ) -> Result<Vec<TaskHandle>>

where D: NetDirProvider + 'static + ?Sized,

Launch the periodic daemon tasks required by the manager to function properly.

Returns a set of TaskHandles that can be used to manage the daemon tasks.

pub fn reconfigure<CFG: CircMgrConfig>( &self, new_config: &CFG, how: Reconfigure ) -> Result<(), ReconfigureError>

Try to change our configuration settings to new_config.

The actual behavior here will depend on the value of how.

pub fn reload_persistent_state(&self) -> Result<()>

Reload state from the state manager.

We only call this method if we don’t have the lock on the state files. If we have the lock, we only want to save.

pub fn upgrade_to_owned_persistent_state(&self) -> Result<()>

Switch from having an unowned persistent state to having an owned one.

Requires that we hold the lock on the state files.

pub fn store_persistent_state(&self) -> Result<bool>

Flush state to the state manager, if there is any unsaved state and we have the lock.

Return true if we saved something; false if we didn’t have the lock.

pub fn update_network_parameters(&self, p: &NetParameters)

👎Deprecated: There is no need to call this function if you have used launch_background_tasks

Reconfigure this circuit manager using the latest set of network parameters.

This is deprecated as a public function: launch_background_tasks now ensures that this happens as needed.

pub fn netdir_is_sufficient(&self, netdir: &NetDir) -> bool

Return true if netdir has enough information to be used for this circuit manager.

(This will check whether the netdir is missing any primary guard microdescriptors)

pub async fn get_or_launch_dir( &self, netdir: DirInfo<'_> ) -> Result<Arc<ClientCirc>>

Return a circuit suitable for sending one-hop BEGINDIR streams, launching it if necessary.

pub async fn get_or_launch_exit( &self, netdir: DirInfo<'_>, ports: &[TargetPort], isolation: StreamIsolation, country_code: Option<CountryCode> ) -> Result<Arc<ClientCirc>>

Return a circuit suitable for exiting to all of the provided ports, launching it if necessary.

If the list of ports is empty, then the chosen circuit will still end at some exit.

pub async fn get_or_launch_dir_specific<T: IntoOwnedChanTarget>( &self, target: T ) -> Result<Arc<ClientCirc>>

Available on crate feature specific-relay only.

Return a circuit to a specific relay, suitable for using for direct (one-hop) directory downloads.

This could be used, for example, to download a descriptor for a bridge.

pub fn builder(&self) -> &CircuitBuilder<R>

Available on crate feature experimental-api only.

Return a reference to the associated CircuitBuilder that this CircMgr will use to create its circuits.

pub fn retire_circ(&self, circ_id: &UniqId)

If circ_id is the unique identifier for a circuit that we’re keeping track of, don’t give it out for any future requests.

pub fn estimate_timeout(&self, timeout_action: &Action) -> Duration

Return an estimate-based delay for how long a given Action should be allowed to complete.

Note that you do not need to use this function in order to get reasonable timeouts for the circuit-building operations provided by the tor-circmgr crate: those, unless specifically noted, always use these timeouts to cancel circuit operations that have taken too long.

Instead, you should only use this function when you need to estimate how long some other operation should take to complete. For example, if you are sending a request over a 3-hop circuit and waiting for a reply, you might choose to wait for estimate_timeout(Action::RoundTrip { length: 3 }).

Note also that this function returns a timeout that the operation should be permitted to complete, not an estimated Duration that the operation will take to complete. Timeouts are chosen to ensure that most operations will complete, but very slow ones will not. So even if we expect that a circuit will complete in (say) 3 seconds, we might still allow a timeout of 4.5 seconds, to ensure that most circuits can complete.

Estimate-based timeouts may change over time, given observations on the actual amount of time needed for circuits to complete building. If not enough information has been gathered, a reasonable default will be used.

pub fn note_external_failure( &self, target: &impl ChanTarget, external_failure: ExternalActivity )

Record that a failure occurred on a circuit with a given guard, in a way that makes us unwilling to use that guard for future circuits.

pub fn note_external_success( &self, target: &impl ChanTarget, external_activity: ExternalActivity )

Record that a success occurred on a circuit with a given guard, in a way that makes us possibly willing to use that guard for future circuits.

pub fn skew_events(&self) -> ClockSkewEvents

Return a stream of events about our estimated clock skew; these events are None when we don’t have enough information to make an estimate, and Some(SkewEstimate) otherwise.

Note that this stream can be lossy: if the estimate changes more than one before you read from the stream, you might only get the most recent update.

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<R: Runtime> Drop for CircMgr<R>

fn drop(&mut self)

Executes the destructor for this type.