Struct 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<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 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 launch_background_tasks<D, S>( self: &Arc<Self>, runtime: &R, dir_provider: &Arc<D>, state_mgr: S, ) -> Result<Vec<TaskHandle>>

where D: NetDirProvider + 'static + ?Sized, S: StateMgr + Send + 'static,

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 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 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 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.

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

Try to change our configuration settings to new_config.

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

Returns whether any of the circuit pools should be cleared.

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 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.