Struct TunnelList 

struct TunnelList<B: AbstractTunnelBuilder<R>, R: Runtime> {
    open_tunnels: HashMap<<B::Tunnel as AbstractTunnel>::Id, OpenEntry<B::Tunnel>>,
    pending_tunnels: PtrWeakHashSet<Weak<PendingEntry<B, R>>, RandomState>,
    pending_requests: PtrWeakHashSet<Weak<PendingRequest<B, R>>, RandomState>,
}

The inner state of an AbstractTunnelMgr.

Fields

open_tunnels: HashMap<<B::Tunnel as AbstractTunnel>::Id, OpenEntry<B::Tunnel>>

A map from tunnel ID to OpenEntry values for all managed open tunnels.

A tunnel is added here from AbstractTunnelMgr::do_launch when we find that it completes successfully, and has not been cancelled. When we decide that such a tunnel should no longer be handed out for any new requests, we “retire” the tunnel by removing it from this map.

pending_tunnels: PtrWeakHashSet<Weak<PendingEntry<B, R>>, RandomState>

Weak-set of PendingEntry for tunnels that are being built.

Because this set only holds weak references, and the only strong reference to the PendingEntry is held by the task building the tunnel, this set’s members are lazily removed after the tunnel is either built or fails to build.

This set is used for two purposes:

1. When a tunnel request finds that there is no open tunnel for its purposes, it checks here to see if there is a pending tunnel that it could wait for.
2. When a pending tunnel finishes building, it checks here to make sure that it has not been cancelled. (Removing an entry from this set marks it as cancelled.)

An entry is added here in AbstractTunnelMgr::prepare_action when we decide that a tunnel needs to be launched.

Later, in AbstractTunnelMgr::do_launch, once the tunnel has finished (or failed), we remove the entry (by pointer identity). If we cannot find the entry, we conclude that the request has been cancelled, and so we discard any tunnel that was created.

pending_requests: PtrWeakHashSet<Weak<PendingRequest<B, R>>, RandomState>

Weak-set of PendingRequest for requests that are waiting for a tunnel to be built.

Because this set only holds weak references, and the only strong reference to the PendingRequest is held by the task waiting for the tunnel to be built, this set’s members are lazily removed after the request succeeds or fails.

Implementations

impl<B: AbstractTunnelBuilder<R>, R: Runtime> TunnelList<B, R>

fn new() -> Self

Make a new empty CircList

fn add_open(&mut self, e: OpenEntry<B::Tunnel>)

Add e to the list of open tunnels.

fn find_open( &mut self, usage: &TargetTunnelUsage, ) -> Option<Vec<&mut OpenEntry<B::Tunnel>>>

Find all the usable open tunnels that support usage.

Return None if there are no such tunnels.

fn get_open_mut( &mut self, id: &<B::Tunnel as AbstractTunnel>::Id, ) -> Option<&mut OpenEntry<B::Tunnel>>

Find an open tunnel by ID.

Return None if no such tunnels exists in this list.

fn take_open( &mut self, id: &<B::Tunnel as AbstractTunnel>::Id, ) -> Option<OpenEntry<B::Tunnel>>

Extract an open tunnel by ID, removing it from this list.

Return None if no such tunnel exists in this list.

fn expire_tunnels( &mut self, now: Instant, params: &ExpirationParameters, ) -> (Option<Instant>, Vec<Weak<B::Tunnel>>)

Remove tunnels based on expiration times.

We remove every unused tunnel that is set to expire by unused_cutoff, and every dirty tunnel that has been dirty since before dirty_cutoff.

Return the next time at which anything will definitely expire, and a list of long-lived tunnels where we need to check their usage status before we can be sure if they are expired.

fn tunnel_should_expire( &mut self, id: &<B::Tunnel as AbstractTunnel>::Id, now: Instant, params: &ExpirationParameters, ) -> Option<ShouldExpire>

Return the time when the tunnel with given id, should expire.

Return None if no such tunnel exists.

fn update_long_lived_tunnel_last_used( &mut self, id: &<B::Tunnel as AbstractTunnel>::Id, now: Instant, params: &ExpirationParameters, disused_since: &Result<Option<Instant>>, ) -> Result<Option<Instant>>

Update the “last known to be in use” time of a long-lived tunnel with ID id, based on learning when it was last used.

Expire the tunnel if appropriate.

If the tunnel is still part of the map, return the next instant at which it might expire.

Returns an error if the tunnel was present but was not already marked as long-lived.

fn add_pending_tunnel(&mut self, pending: Arc<PendingEntry<B, R>>)

Add pending to the set of in-progress tunnels.

fn find_pending_tunnels( &self, usage: &TargetTunnelUsage, ) -> Option<Vec<Arc<PendingEntry<B, R>>>>

Find all pending tunnels that support usage.

If no such tunnels are currently being built, return None.

fn tunnel_is_pending(&self, circ: &Arc<PendingEntry<B, R>>) -> bool

Return true if circ is still pending.

A tunnel will become non-pending when finishes (successfully or not), or when it’s removed from this list via clear_all_tunnels().

fn add_pending_request(&mut self, pending: &Arc<PendingRequest<B, R>>)

Construct and add a new entry to the set of request waiting for a tunnel.

Return the request, and a new receiver stream that it should use for notification of possible tunnels to use.

fn find_pending_requests( &self, circ_spec: &SupportedTunnelUsage, ) -> Vec<Arc<PendingRequest<B, R>>>

Return all pending requests that would be satisfied by a tunnel that supports circ_spec.

fn clear_all_tunnels(&mut self)

Clear all pending and open tunnels.

Calling clear_all_tunnels ensures that any request that is answered after this method runs will receive a tunnels that was launched after this method runs.