Struct tor_circmgr::CircMgr

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

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.

Implementations

impl<R: Runtime> CircMgr<R>

pub fn new<SM>(
    config: CircMgrConfig,
    storage: SM,
    runtime: &R,
    chanmgr: Arc<ChanMgr<R>>
) -> Result<Arc<Self>> where
    SM: StateMgr + Send + Sync + 'static, 

Construct a new circuit manager.

pub fn reconfigure(
    &self,
    new_config: &CircMgrConfig,
    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<()>

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

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

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

(NOTE: for now, this only affects circuit timeout estimation.)

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 update_network(&self, netdir: &NetDir)

Reconfigure this circuit manager using the latest network directory.

This should be called on any change to the network, as opposed to CircMgr::update_network_parameters, which should only be called when the parameters change.

pub async fn get_or_launch_dir(&self, netdir: DirInfo<'_>) -> Result<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
) -> Result<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 launch_circuits_preemptively(&self, netdir: DirInfo<'_>)

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

Note

This function is invoked periodically from the arti-client crate, based on timings from the network parameters. As with launch_timeout_testing_circuit_if_appropriate, this should ideally be refactored to be internal to this crate, and not be a public API here.

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 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 the arti-client crate, based on timings from the network parameters. Please don’t invoke it on your own; I hope we can have this API go away in the future.

I would much prefer to have this not be a public API, and instead have it be a daemon task. The trouble is that it needs to get a NetDir as input, and that isn’t possible with the current CircMgr design. See arti#161.

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.