Trait AbstractCircBuilder

pub(crate) trait AbstractCircBuilder<R: Runtime>: Send + Sync {
    type Circ: AbstractCirc + Send + Sync;
    type Plan: Send + Debug + MockablePlan;

    // Required methods
    fn plan_circuit(
        &self,
        usage: &TargetCircUsage,
        dir: DirInfo<'_>,
    ) -> Result<(Self::Plan, SupportedCircUsage)>;
    fn build_circuit<'life0, 'async_trait>(
        &'life0 self,
        plan: Self::Plan,
    ) -> Pin<Box<dyn Future<Output = Result<(SupportedCircUsage, Arc<Self::Circ>)>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn learning_timeouts(&self) -> bool;
    fn save_state(&self) -> Result<bool>;
    fn path_config(&self) -> Arc<PathConfig>;
    fn set_path_config(&self, new_config: PathConfig);
    fn estimator(&self) -> &Estimator;
    fn vanguardmgr(&self) -> &Arc<VanguardMgr<R>>;
    fn upgrade_to_owned_state(&self) -> Result<()>;
    fn reload_state(&self) -> Result<()>;
    fn guardmgr(&self) -> &GuardMgr<R>;
    fn update_network_parameters(&self, p: &NetParameters);

    // Provided methods
    fn launch_parallelism(&self, usage: &TargetCircUsage) -> usize { ... }
    fn select_parallelism(&self, usage: &TargetCircUsage) -> 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 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: &TargetCircUsage, dir: DirInfo<'_>, ) -> Result<(Self::Plan, SupportedCircUsage)>

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<(SupportedCircUsage, 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.

fn save_state(&self) -> Result<bool>

Flush state to the state manager if we own the lock.

Return Ok(true) if we saved, and Ok(false) if we didn’t hold the lock.

fn path_config(&self) -> Arc<PathConfig>

Return this builder’s PathConfig.

fn set_path_config(&self, new_config: PathConfig)

Replace this builder’s PathConfig.

fn estimator(&self) -> &Estimator

Return a reference to this builder’s timeout estimator.

fn vanguardmgr(&self) -> &Arc<VanguardMgr<R>>

Available on crate feature vanguards only.

Return a reference to this builder’s VanguardMgr.

fn upgrade_to_owned_state(&self) -> Result<()>

Replace our state with a new owning state, assuming we have storage permission.

fn reload_state(&self) -> Result<()>

Reload persistent state from disk, if we don’t have storage permission.

fn guardmgr(&self) -> &GuardMgr<R>

Return a reference to this builder’s GuardMgr.

fn update_network_parameters(&self, p: &NetParameters)

Reconfigure this builder using the latest set of network parameters.

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

Provided Methods

fn launch_parallelism(&self, usage: &TargetCircUsage) -> 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: &TargetCircUsage) -> 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<R> for CircuitBuilder<R>

type Circ = ClientCirc

type Plan = Plan