Struct AbstractTunnelMgr 

pub(crate) struct AbstractTunnelMgr<B: AbstractTunnelBuilder<R>, R: Runtime> {
    builder: B,
    runtime: R,
    tunnels: Mutex<TunnelList<B, R>>,
    circuit_timing: MutCfg<CircuitTiming>,
    unused_timing: Mutex<UnusedTimings>,
}

Abstract implementation for tunnel management.

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

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

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

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

Fields

builder: B

Builder used to construct tunnels.

runtime: R

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

tunnels: Mutex<TunnelList<B, R>>

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

circuit_timing: MutCfg<CircuitTiming>

Configured information about when to expire tunnels and requests.

unused_timing: Mutex<UnusedTimings>

Minimum lifetime of an unused tunnel.

Derived from the network parameters.

Implementations

impl<B: AbstractTunnelBuilder<R> + 'static, R: Runtime> AbstractTunnelMgr<B, R>

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

Construct a new AbstractTunnelMgr.

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: &TargetTunnelUsage, dir: DirInfo<'_>, ) -> Result<(Arc<B::Tunnel>, TunnelProvenance)>

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 AbstractTunnelMgr.

fn prepare_action( &self, usage: &TargetTunnelUsage, dir: DirInfo<'_>, restrict_circ: bool, ) -> Result<Action<B, R>>

Choose which action we should take in order to provide a tunnel 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, R>, usage: &TargetTunnelUsage, ) -> Result<(Arc<B::Tunnel>, TunnelProvenance), RetryError<Box<Error>>>

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

fn plan_by_usage( &self, dir: DirInfo<'_>, usage: &TargetTunnelUsage, ) -> Result<(Arc<PendingEntry<B, R>>, TunnelBuildPlan<B, R>)>

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

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 tunnel.

pub(crate) fn launch_by_usage( self: &Arc<Self>, usage: &TargetTunnelUsage, dir: DirInfo<'_>, ) -> Result<Shared<Receiver<Result<<<B as AbstractTunnelBuilder<R>>::Tunnel as AbstractTunnel>::Id>>>>

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

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

fn spawn_launch( self: Arc<Self>, usage: &TargetTunnelUsage, plan: TunnelBuildPlan<B, R>, ) -> Shared<Receiver<Result<<<B as AbstractTunnelBuilder<R>>::Tunnel as AbstractTunnel>::Id>>>

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

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

async fn do_launch( self: Arc<Self>, plan: <B as AbstractTunnelBuilder<R>>::Plan, pending: Arc<PendingEntry<B, R>>, ) -> (Option<SupportedTunnelUsage>, Result<<<B as AbstractTunnelBuilder<R>>::Tunnel as AbstractTunnel>::Id>)

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

fn expiration_params(&self) -> ExpirationParameters

Return the currently configured expiration parameters.

pub(crate) async fn launch_unmanaged( &self, usage: &TargetTunnelUsage, dir: DirInfo<'_>, ) -> Result<(SupportedTunnelUsage, B::Tunnel)>

Plan and launch a new tunnel to a given target, bypassing our managed pool of tunnels.

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

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

pub(crate) fn take_tunnel( &self, id: &<B::Tunnel as AbstractTunnel>::Id, ) -> Option<Arc<B::Tunnel>>

Remove the tunnel with a given id from this manager.

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

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

pub(crate) fn retire_all_tunnels(&self)

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

Calling retire_all_tunnels ensures that any tunnel request that gets an answer after this method runs will receive a tunnel 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 tunnels that are built using the new configuration.

pub(crate) async fn expire_tunnels(&self, now: Instant) -> Option<Instant>

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

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

Return the earliest time at which any current tunnel will expire.

pub(crate) async fn consider_expiring_tunnel( &self, tun_id: &<B::Tunnel as AbstractTunnel>::Id, now: Instant, ) -> Result<Option<Instant>>

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

Returns None if the circuit is expired; otherwise returns the next time at which the circuit may expire.

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

Return the number of open tunnels held by this tunnel 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 tunnel should expire from now if it has not yet been used