Struct tor_dirmgr::bridgedesc::State

struct State {
    config: Arc<BridgeDescDownloadConfig>,
    subscribers: FlagPublisher<BridgeDescEvent>,
    current: Arc<BridgeDescList>,
    running: HashMap<BridgeConfig, RunningInfo>,
    queued: VecDeque<QueuedEntry>,
    dormancy: Dormancy,
    refetch_schedule: BinaryHeap<RefetchEntry<SystemTime, ()>>,
    retry_schedule: BinaryHeap<RefetchEntry<Instant, RetryDelay>>,
    earliest_timeout: Sender<Option<Instant>>,
}

Available on crate feature bridge-client only.

State: our downloaded descriptors (cache), and records of what we’re doing

Various functions (both tasks and public entrypoints), which generally start with a Manager, lock the mutex and modify this.

Generally, the flow is:

• A public entrypoint, or task, obtains a StateGuard. It modifies the state to represent the callers’ new requirements, or things it has done, by updating the state, preserving the invariants but disturbing the “liveness” (see below).

• StateGuard::drop calls State::process. This restores the liveness properties.

Possible states of a bridge:

A bridge can be in one of the following states, represented by its presence in these particular data structures inside State:

• running/queued: newly added, no outcome yet.
• current + running/queued: we are fetching (or going to)
• current = OK + refetch_schedule: fetched OK, will refetch before expiry
• current = Err + retry_schedule: failed, will retry at some point

Invariants:

Can be disrupted in the middle of a principal function, but should be restored on return.

• Tracked: Each bridge appears at most once in running, queued, refetch_schedule and retry_schedule. We call such a bridge Tracked.

• Current Every bridge in current is Tracked. (But not every Tracked bridge is necessarily in current, yet.)

• Schedules Every bridge in refetch_schedule or retry_schedule is also in current.

• Input: Exactly each bridge that was passed to the last call to set_bridges() is Tracked. (If we encountered spawn failures, we treat this as trying to shut down, so we cease attempts to get bridges, and discard the relevant state, violating this.)

• Limit: running is capped at the effective parallelism: zero if we are dormant, the configured parallelism otherwise.

Liveness properties:

These can be disrupted by any function which holds a StateGuard. Will be restored by process(), which is called when StateGuard is dropped.

Functions that take a StateGuard may disturb these invariants and rely on someone else to restore them.

• Running: If queued is nonempty, running is full.

• Timeout: earliest_timeout is the earliest timeout in either retry_schedule or refetch_schedule. (Disturbances of this property which occur due to system time warps are not necessarily detected and remedied in a timely way, but will be remedied no later than after max_refetch.)

Fields

config: Arc<BridgeDescDownloadConfig>

Our configuration

subscribers: FlagPublisher<BridgeDescEvent>

People who will be told when current changes.

current: Arc<BridgeDescList>

Our current idea of our output, which we give out handles onto.

running: HashMap<BridgeConfig, RunningInfo>

Bridges whose descriptors we are currently downloading.

queued: VecDeque<QueuedEntry>

Bridges which we want to download, but we’re waiting for running to be less than effective_parallelism().

dormancy: Dormancy

Are we dormant?

refetch_schedule: BinaryHeap<RefetchEntry<SystemTime, ()>>

Bridges that we have a descriptor for, and when they should be refetched due to validity expiry.

This is indexed by SystemTime because that helps avoids undesirable behaviors when the system clock changes.

retry_schedule: BinaryHeap<RefetchEntry<Instant, RetryDelay>>

Bridges that failed earlier, and when they should be retried.

earliest_timeout: Sender<Option<Instant>>

Earliest time from either retry_schedule or refetch_schedule

None means “wait indefinitely”.

Implementations

impl State

fn process<R: Runtime, M: Mockable<R>>(&mut self, mgr: &Arc<Manager<R, M>>)

Ensure progress is made, by restoring all the liveness invariants

This includes launching circuits as needed.

fn consider_launching<R: Runtime, M: Mockable<R>>( &mut self, mgr: &Arc<Manager<R, M>> )

Launch download attempts if we can

Specifically: if we have things in queued, and running is shorter than effective_parallelism(), we launch task(s) to attempt download(s).

Restores liveness invariant Running.

Idempotent. Forms part of process.

fn modify_current<T, F: FnOnce(&mut BridgeDescList) -> T>(&mut self, f: F) -> T

Modify current and notify subscribers

Helper function which modifies only current, not any of the rest of the state. it is the caller’s responsibility to ensure that the invariants are upheld.

The implementation actually involves cloning current, so it is best to amortize calls to this function.

fn set_current_and_notify<BDL: Into<Arc<BridgeDescList>>>(&mut self, new: BDL)

Set current to a value and notify

Helper function which modifies only current, not any of the rest of the state. it is the caller’s responsibility to ensure that the invariants are upheld.

fn effective_parallelism(&self) -> usize

Obtain the currently-desired level of parallelism

Helper function. The return value depends the mutable state and also the config.

This is how we implement dormancy.

Trait Implementations

impl Debug for State

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.