Struct ChecklistSet 

pub struct ChecklistSet { /* private fields */ }

The ordered set of checklists, one per data stream (§6.1.2, §6.1.2.6).

Implementations

impl ChecklistSet

pub fn new() -> Self

An empty set.

pub fn push(&mut self, checklist: Checklist)

Append a checklist. The order is the “usage-defined checklist set order” §6.1.2.6 unfreezes against.

pub fn checklists(&self) -> &[Checklist]

The checklists, in order.

pub fn checklists_mut(&mut self) -> &mut [Checklist]

The checklists, mutably.

pub fn is_empty(&self) -> bool

Whether the set holds no checklists at all.

pub fn pair(&self, id: PairId) -> Option<&CandidatePair>

The pair with this identity, wherever it is.

pub fn pair_mut(&mut self, id: PairId) -> Option<&mut CandidatePair>

The pair with this identity, mutably.

pub fn checklist_of(&self, id: PairId) -> Option<usize>

Which checklist holds this pair.

pub fn total_pairs(&self) -> usize

N in §14.3’s RTO: the total number of connectivity checks to be performed.

pub fn outstanding(&self) -> usize

Num-Waiting + Num-In-Progress in §14.3’s RTO, across the set.

pub fn limit(&mut self, limit: usize)

§6.1.2.5: discard the lowest-priority pairs until the set holds at most limit of them.

The limit is an attack control and not tidiness — it bounds how many packets a hostile candidate list can make sipx send — which is why §6.1.2.5 makes it a MUST and makes it configurable. The discarding is spread across checklists (“SHOULD be done evenly so that the number of candidate pairs in each checklist is reduced the same amount”) by always taking from the longest checklist.

Only pairs that have not been checked, or have finished failing, are discardable. §6.1.2.5 runs at checklist formation, when every pair is Frozen; this runs again every time §7.3.1.4 inserts a pair, because that is the path a peer can drive. Discarding an In-Progress pair would orphan its transaction, and discarding a Succeeded one would take a working path out of the valid list — so a set already full of live pairs stops shrinking rather than tearing itself down, and the limit then binds by refusing growth.

pub fn compute_initial_states(&mut self)

§6.1.2.6’s initial states: everything Frozen, every checklist Running, and then exactly one pair per foundation moved to Waiting.

The pair to unfreeze is “the first candidate pair (ordered by the lowest component ID and then the highest priority if component IDs are equal) in the first checklist … that has that foundation”, and a foundation already unfrozen in an earlier checklist is not unfrozen again. RFC 8445’s own Table 1 walks the case that distinguishes this from RFC 5245’s rule, and the_rfcs_three_checklist_five_foundation_example_unfreezes_five_pairs asserts it cell by cell.

pub fn unfreeze_added(&mut self)

§6.1.2, applied to a set that has grown: “if candidates are added to a checklist … the agent will re-perform these steps for the updated checklist”.

The same rule as §6.1.2.6 step 4, expressed over whatever is Frozen now: for each foundation that has no pair anywhere in the set outside the Frozen state, the first Frozen pair with it — by lowest component ID, then highest priority, in the first checklist that has it — moves to Waiting. Run over a set where everything is Frozen this is step 4; run over a live set it unfreezes exactly the foundations the new pairs brought.

pub fn unfreeze_foundation(&mut self, foundation: &PairFoundation)

§7.2.5.3.3: every Frozen pair in every checklist that shares this foundation moves to Waiting.

pub fn unfreeze_idle(&mut self, index: usize)

§6.1.4.2 step 2: with nothing Waiting in this checklist and something Frozen in it, unfreeze the Frozen pairs whose foundation has no pair Waiting or In-Progress anywhere in the set.

This is the second unfreeze trigger, and the one that is easy to miss. Without it, a foundation whose one unfrozen pair failed leaves its remaining pairs Frozen for the rest of the session — §6.1.2.6 unfreezes each foundation exactly once, and §7.2.5.3.3 only ever unfreezes on success — so ICE reports a failure for a path it never finished checking.

pub fn next_active(&mut self) -> Option<usize>

The next checklist Ta may act on, round-robin (§6.1.4.2).

“Whenever Ta fires the next checklist in the Running state in the checklist set is picked … After the last checklist in the Running state has been processed, the first checklist is picked again.” A Completed checklist is included when it still has a triggered check queued, because §8.1.2 requires an agent to keep answering for a concluded stream and §8.1.1’s tolerance clause depends on it.

pub fn recompute_priorities( &mut self, role: Role, locals: &[LocalCandidate], remotes: &[RemoteCandidate], )

Recompute every pair priority and re-sort every checklist (§6.1.2.3).

A role change swaps which side is G and which is D, so this runs on every role change — forgetting it is one of the two ways role conflict is mishandled, and the other is not detecting the conflict at all.

Trait Implementations

impl Debug for ChecklistSet

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

Formats the value using the given formatter.

impl Default for ChecklistSet

fn default() -> ChecklistSet

Returns the “default value” for a type.