Struct tor_circmgr::mgr::AbstractCircMgr

pub(crate) struct AbstractCircMgr<B: AbstractCircBuilder, R: Runtime> {
    builder: B,
    runtime: R,
    circs: Mutex<CircList<B>>,
    circuit_timing: MutCfg<CircuitTiming>,
    unused_timing: Mutex<UnusedTimings>,
}

Abstract implementation for circuit management.

The algorithm provided here is fairly simple. In its simplest form:

When somebody asks for a circuit for a given operation: if we find one open already, we return it. If we find in-progress circuits that would meet our needs, we wait for one to finish (or for all to fail). And otherwise, we launch one or more circuits to meet the request’s needs.

If this process fails, then we retry it, up to a timeout or a numerical limit.

If a circuit not previously considered for a given request finishes before the request is satisfied, and if the circuit would satisfy the request, we try to give that circuit as an answer to that request even if it was not one of the circuits that request was waiting for.

Fields

builder: B

Builder used to construct circuits.

runtime: R

An asynchronous runtime to use for launching tasks and checking timeouts.

circs: Mutex<CircList<B>>

A CircList to manage our list of circuits, requests, and pending circuits.

circuit_timing: MutCfg<CircuitTiming>

Configured information about when to expire circuits and requests.

unused_timing: Mutex<UnusedTimings>

Minimum lifetime of an unused circuit.

Derived from the network parameters.

Implementations

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

pub(crate) fn new(builder: B, runtime: R, circuit_timing: CircuitTiming) -> Self

Construct a new AbstractCircMgr.

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

Reconfigure this manager using the latest set of network parameters.

pub(crate) fn circuit_timing(&self) -> Arc<CircuitTiming>

Return this manager’s CircuitTiming.

pub(crate) fn set_circuit_timing(&self, new_config: CircuitTiming)

Return this manager’s CircuitTiming.

pub(crate) async fn get_or_launch( self: &Arc<Self>, usage: &<B::Spec as AbstractSpec>::Usage, dir: DirInfo<'_> ) -> Result<(Arc<B::Circ>, CircProvenance)>

Return a circuit suitable for use with a given usage, creating that circuit if necessary, and restricting it under the assumption that it will be used for that spec.

This is the primary entry point for AbstractCircMgr.

pub(crate) async fn ensure_circuit( self: &Arc<Self>, usage: &<B::Spec as AbstractSpec>::Usage, dir: DirInfo<'_> ) -> Result<()>

Make sure a circuit exists, without actually asking for it.

Make sure that there is a circuit (built or in-progress) that could be used for usage, and launch one or more circuits in a background task if there is not.

fn prepare_action( &self, usage: &<B::Spec as AbstractSpec>::Usage, dir: DirInfo<'_>, restrict_circ: bool ) -> Result<Action<B>>

Choose which action we should take in order to provide a circuit for a given usage.

If restrict_circ is true, we restrict the spec of any circ we decide to use to mark that it is being used for usage.

async fn take_action( self: Arc<Self>, act: Action<B>, usage: &<B::Spec as AbstractSpec>::Usage ) -> Result<(Arc<B::Circ>, CircProvenance), RetryError<Box<Error>>>

Execute an action returned by pick-action, and return the resulting circuit or error.

fn plan_by_usage( &self, dir: DirInfo<'_>, usage: &<B::Spec as AbstractSpec>::Usage ) -> Result<(Arc<PendingEntry<B>>, CircBuildPlan<B>)>

Given a directory and usage, compute the necessary objects to build a circuit: A PendingEntry to keep track of the in-process circuit, and a CircBuildPlan that we’ll give to the thread that will build the circuit.

The caller should probably add the resulting PendingEntry to self.circs.

This is an internal function that we call when we’re pretty sure we want to build a circuit.

pub(crate) fn launch_by_usage( self: &Arc<Self>, usage: &<B::Spec as AbstractSpec>::Usage, dir: DirInfo<'_> ) -> Result<Shared<Receiver<Result<<<B as AbstractCircBuilder>::Circ as AbstractCirc>::Id>>>>

Launch a managed circuit for a target usage, without checking whether one already exists or is pending.

Return a listener that will be informed when the circuit is done.

fn spawn_launch( self: Arc<Self>, usage: &<B::Spec as AbstractSpec>::Usage, plan: CircBuildPlan<B> ) -> Shared<Receiver<Result<<<B as AbstractCircBuilder>::Circ as AbstractCirc>::Id>>>

Spawn a background task to launch a circuit, and report its status.

The usage argument is the usage from the original request that made us build this circuit.

async fn do_launch( self: Arc<Self>, plan: <B as AbstractCircBuilder>::Plan, pending: Arc<PendingEntry<B>> ) -> (Option<<B as AbstractCircBuilder>::Spec>, Result<<<B as AbstractCircBuilder>::Circ as AbstractCirc>::Id>)

Run in the background to launch a circuit. Return a 2-tuple of the new circuit spec and the outcome that should be sent to the initiator.

pub(crate) async fn launch_unmanaged( &self, usage: &<B::Spec as AbstractSpec>::Usage, dir: DirInfo<'_> ) -> Result<(<B as AbstractCircBuilder>::Spec, Arc<B::Circ>)>

Available on crate feature hs-common only.

Plan and launch a new circuit to a given target, bypassing our managed pool of circuits.

This method will always return a new circuit, and never return a circuit that this CircMgr gives out for anything else.

The new circuit will participate in the guard and timeout apparatus as appropriate, no retry attempt will be made if the circuit fails.

pub(crate) fn take_circ( &self, id: &<B::Circ as AbstractCirc>::Id ) -> Option<Arc<B::Circ>>

Remove the circuit with a given id from this manager.

After this function is called, that circuit will no longer be handed out to any future requests.

Return None if we have no circuit with the given ID.

pub(crate) fn retire_all_circuits(&self)

Remove all open and pending circuits and from this manager, to ensure they can’t be given out for any more requests.

Calling retire_all_circuits ensures that any circuit request that gets an answer after this method runs will receive a circuit that was launched after this method runs.

We call this method this when our configuration changes in such a way that we want to make sure that any new (or pending) requests will receive circuits that are built using the new configuration.

pub(crate) fn expire_circs(&self, now: Instant)

Expire circuits according to the rules in config and the current time now.

Expired circuits will not be automatically closed, but they will no longer be given out for new circuits.

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

Consider expiring the circuit with given circuit id, according to the rules in config and the current time now.

pub(crate) fn n_circs(&self) -> usize

Return the number of open circuits held by this circuit manager.

pub(crate) fn peek_runtime(&self) -> &R

Get a reference to this manager’s runtime.

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

Get a reference to this manager’s builder.

fn pick_use_duration(&self) -> Duration

Pick a duration by when a new circuit should expire from now if it has not yet been used