Trait tor_circmgr::mgr::AbstractCircBuilder

pub(crate) trait AbstractCircBuilder: Send + Sync {
    type Spec: AbstractSpec + Debug + Send + Sync;
    type Circ: AbstractCirc + Send + Sync;
    type Plan: Send + Debug + MockablePlan;

    // Required methods
    fn plan_circuit(
        &self,
        usage: &<Self::Spec as AbstractSpec>::Usage,
        dir: DirInfo<'_>
    ) -> Result<(Self::Plan, Self::Spec)>;
    fn build_circuit<'life0, 'async_trait>(
        &'life0 self,
        plan: Self::Plan
    ) -> Pin<Box<dyn Future<Output = Result<(Self::Spec, Arc<Self::Circ>)>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn learning_timeouts(&self) -> bool;

    // Provided methods
    fn launch_parallelism(
        &self,
        usage: &<Self::Spec as AbstractSpec>::Usage
    ) -> usize { ... }
    fn select_parallelism(
        &self,
        usage: &<Self::Spec as AbstractSpec>::Usage
    ) -> usize { ... }
}

An object that knows how to build circuits.

AbstractCircBuilder creates circuits in two phases. First, a plan is made for how to build the circuit. This planning phase should be relatively fast, and must not suspend or block. Its purpose is to get an early estimate of which operations the circuit will be able to support when it’s done.

Second, the circuit is actually built, using the plan as input.

Required Associated Types

type Spec: AbstractSpec + Debug + Send + Sync

The specification type describing what operations circuits can be used for.

type Circ: AbstractCirc + Send + Sync

The circuit type that this builder knows how to build.

type Plan: Send + Debug + MockablePlan

An opaque type describing how a given circuit will be built. It may represent some or all of a path-or it may not.

Required Methods

fn plan_circuit( &self, usage: &<Self::Spec as AbstractSpec>::Usage, dir: DirInfo<'_> ) -> Result<(Self::Plan, Self::Spec)>

Form a plan for how to build a new circuit that supports usage.

Return an opaque Plan object, and a new spec describing what the circuit will actually support when it’s built. (For example, if the input spec requests a circuit that connect to port 80, then “planning” the circuit might involve picking an exit that supports port 80, and the resulting spec might be the exit’s complete list of supported ports.)

Requirements

The resulting Spec must support usage.

fn build_circuit<'life0, 'async_trait>( &'life0 self, plan: Self::Plan ) -> Pin<Box<dyn Future<Output = Result<(Self::Spec, Arc<Self::Circ>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Construct a circuit according to a given plan.

On success, return a spec describing what the circuit can be used for, and the circuit that was just constructed.

This function should implement some kind of a timeout for circuits that are taking too long.

Requirements

The spec that this function returns must support the usage that was originally passed to plan_circuit. It must also contain the spec that was originally returned by plan_circuit.

fn learning_timeouts(&self) -> bool

Return true if we are currently attempting to learn circuit timeouts by building testing circuits.

Provided Methods

fn launch_parallelism( &self, usage: &<Self::Spec as AbstractSpec>::Usage ) -> usize

Return a “parallelism factor” with which circuits should be constructed for a given purpose.

If this function returns N, then whenever we launch circuits for this purpose, then we launch N in parallel.

The default implementation returns 1. The value of 0 is treated as if it were 1.

fn select_parallelism( &self, usage: &<Self::Spec as AbstractSpec>::Usage ) -> usize

Return a “parallelism factor” for which circuits should be used for a given purpose.

If this function returns N, then whenever we select among open circuits for this purpose, we choose at random from the best N.

The default implementation returns 1. The value of 0 is treated as if it were 1.

Implementors

impl<R: Runtime> AbstractCircBuilder for CircuitBuilder<R>

type Circ = ClientCirc

type Spec = SupportedCircUsage

type Plan = Plan