Struct CircMgrInner

pub(crate) struct CircMgrInner<B: AbstractCircBuilder<R> + 'static, R: Runtime> {
    pub(crate) mgr: Arc<AbstractCircMgr<B, R>>,
    pub(crate) predictor: Arc<Mutex<PreemptiveCircuitPredictor>>,
}

Internal object used to implement CircMgr, which allows for mocking.

Fields

mgr: Arc<AbstractCircMgr<B, R>>

The underlying circuit manager object that implements our behavior.

predictor: Arc<Mutex<PreemptiveCircuitPredictor>>

A preemptive circuit predictor, for, uh, building circuits preemptively.

Implementations

impl<R: Runtime> CircMgrInner<CircuitBuilder<R>, R>

pub(crate) 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.

impl<B: AbstractCircBuilder<R> + 'static, R: Runtime> CircMgrInner<B, R>

pub(crate) fn new_generic<CFG: CircMgrConfig>( config: &CFG, runtime: &R, guardmgr: &GuardMgr<R>, builder: B, ) -> Self

Generic implementation for CircMgrInner::new

pub(crate) 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 [TaskHandle]s that can be used to manage the daemon tasks.

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

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

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

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(crate) async fn get_or_launch_dir_specific<T: IntoOwnedChanTarget>( &self, target: T, ) -> Result<Arc<B::Circ>>

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(crate) 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(crate) async fn keep_circmgr_params_updated<D>( events: impl Stream<Item = DirEvent> + Unpin, circmgr: Weak<Self>, dirmgr: Weak<D>, )

where D: NetDirProvider + 'static + ?Sized,

Whenever a DirEvent::NewConsensus arrives on events, update circmgr with the consensus parameters from dirmgr.

Exit when events is closed, or one of circmgr or dirmgr becomes dangling.

This is a daemon task: it runs indefinitely in the background.

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

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

pub(crate) async fn continually_launch_timeout_testing_circuits<D>( sched: TaskSchedule<R>, circmgr: Weak<Self>, dirmgr: Weak<D>, )

where D: NetDirProvider + 'static + ?Sized,

Run indefinitely, launching circuits as needed to get a good estimate for our circuit build timeouts.

Exit when we notice that circmgr or dirmgr has been dropped.

This is a daemon task: it runs indefinitely in the background.

pub(crate) fn launch_timeout_testing_circuit_if_appropriate( &self, netdir: &NetDir, ) -> Result<()>

If we need to launch a testing circuit to judge our circuit build timeouts timeouts, do so.

Note

This function is invoked periodically from continually_launch_timeout_testing_circuits.

pub(crate) async fn update_persistent_state<S>( sched: TaskSchedule<R>, circmgr: Weak<Self>, statemgr: S, )

where S: StateMgr + Send,

Run forever, periodically telling circmgr to update its persistent state.

Exit when we notice that circmgr has been dropped.

This is a daemon task: it runs indefinitely in the background.

pub(crate) 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(crate) 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(crate) async fn continually_preemptively_build_circuits<D>( sched: TaskSchedule<R>, circmgr: Weak<Self>, dirmgr: Weak<D>, )

where D: NetDirProvider + 'static + ?Sized,

Run indefinitely, launching circuits where the preemptive circuit predictor thinks it’d be a good idea to have them.

Exit when we notice that circmgr or dirmgr has been dropped.

This is a daemon task: it runs indefinitely in the background.

Note

This would be better handled entirely within tor-circmgr, like other daemon tasks.

pub(crate) async fn launch_circuits_preemptively( &self, netdir: DirInfo<'_>, ) -> Result<(), PreemptiveCircError>

Launch circuits preemptively, using the preemptive circuit predictor’s predictions.

Note

This function is invoked periodically from continually_preemptively_build_circuits().

pub(crate) async fn launch_hs_unmanaged<T>( &self, planned_target: Option<T>, dir: &NetDir, stem_kind: HsCircStemKind, circ_kind: Option<HsCircKind>, ) -> Result<Arc<B::Circ>>

where T: IntoOwnedChanTarget,

Available on crate feature hs-common only.

Create and return a new (typically anonymous) onion circuit stem of type stem_kind.

If circ_kind is provided, we apply additional rules to make sure that this will be usable as a stem for the given kind of onion service circuit. Otherwise, we pick a stem that will probably be useful in general.

This circuit is guaranteed not to have been used for any traffic previously, and it will not be given out for any other requests in the future unless explicitly re-registered with a circuit manager.

If planned_target is provided, then the circuit will be built so that it does not share any family members with the provided target. (The circuit will not be extended to that target itself!)

Used to implement onion service clients and services.

pub(crate) 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(crate) fn estimate_timeout(&self, timeout_action: &Action) -> Duration

Internal implementation for CircMgr::estimate_timeout.

pub(crate) fn builder(&self) -> &B

Internal implementation for CircMgr::builder.

pub(crate) 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(crate) fn expire_circuits(&self)

Expire every circuit that has been dirty for too long.

Expired circuits are not closed while they still have users, but they are no longer given out for new requests.

pub(crate) fn retire_all_circuits(&self)

Mark every circuit that we have launched so far as unsuitable for any future requests. This won’t close existing circuits that have streams attached to them, but it will prevent any future streams from being attached.

TODO: we may want to expose this eventually. If we do, we should be very clear that you don’t want to use it haphazardly.

pub(crate) fn retire_circ(&self, circ_id: &<B::Circ as AbstractCirc>::Id)

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(crate) 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(crate) 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(crate) 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.

Trait Implementations

impl<B: Clone + AbstractCircBuilder<R> + 'static, R: Clone + Runtime> Clone for CircMgrInner<B, R>

fn clone(&self) -> CircMgrInner<B, R>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<B: AbstractCircBuilder<R> + 'static, R: Runtime> Drop for CircMgrInner<B, R>

fn drop(&mut self)

Executes the destructor for this type.