Struct tor_circmgr::mgr::CircList

struct CircList<B: AbstractCircBuilder> {
    open_circs: HashMap<<B::Circ as AbstractCirc>::Id, OpenEntry<B::Spec, B::Circ>>,
    pending_circs: PtrWeakHashSet<Weak<PendingEntry<B>>>,
    pending_requests: PtrWeakHashSet<Weak<PendingRequest<B>>>,
}

The inner state of an AbstractCircMgr.

Fields

open_circs: HashMap<<B::Circ as AbstractCirc>::Id, OpenEntry<B::Spec, B::Circ>>

A map from circuit ID to OpenEntry values for all managed open circuits.

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

pending_circs: PtrWeakHashSet<Weak<PendingEntry<B>>>

Weak-set of PendingEntry for circuits 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 circuit, this set’s members are lazily removed after the circuit is either built or fails to build.

This set is used for two purposes:

1. When a circuit request finds that there is no open circuit for its purposes, it checks here to see if there is a pending circuit that it could wait for.
2. When a pending circuit 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 AbstractCircMgr::prepare_action when we decide that a circuit needs to be launched.

Later, in AbstractCircMgr::do_launch, once the circuit 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 circuit that was created.

pending_requests: PtrWeakHashSet<Weak<PendingRequest<B>>>

Weak-set of PendingRequest for requests that are waiting for a circuit 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 circuit to be built, this set’s members are lazily removed after the request succeeds or fails.

Implementations

impl<B: AbstractCircBuilder> CircList<B>

fn new() -> Self

Make a new empty CircList

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

Add e to the list of open circuits.

fn find_open( &mut self, usage: &<B::Spec as AbstractSpec>::Usage ) -> Option<Vec<&mut OpenEntry<B::Spec, B::Circ>>>

Find all the usable open circuits that support usage.

Return None if there are no such circuits.

fn get_open_mut( &mut self, id: &<B::Circ as AbstractCirc>::Id ) -> Option<&mut OpenEntry<B::Spec, B::Circ>>

Find an open circuit by ID.

Return None if no such circuit exists in this list.

fn take_open( &mut self, id: &<B::Circ as AbstractCirc>::Id ) -> Option<OpenEntry<B::Spec, B::Circ>>

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

Return None if no such circuit exists in this list.

fn expire_circs(&mut self, unused_cutoff: Instant, dirty_cutoff: Instant)

Remove circuits based on expiration times.

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

fn expire_circ( &mut self, id: &<B::Circ as AbstractCirc>::Id, unused_cutoff: Instant, dirty_cutoff: Instant )

Remove the circuit with given id, if it is scheduled to expire now, according to the provided expiration times.

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

Add pending to the set of in-progress circuits.

fn find_pending_circs( &self, usage: &<B::Spec as AbstractSpec>::Usage ) -> Option<Vec<Arc<PendingEntry<B>>>>

Find all pending circuits that support usage.

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

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

Return true if circ is still pending.

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

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

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

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

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

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

fn clear_all_circuits(&mut self)

Clear all pending circuits and open circuits.

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