Module weight

Functions for applying the correct weights to relays when choosing a relay at random.

The weight to use when picking a relay depends on several factors:

• The relay’s apparent bandwidth. (This is ideally measured by a set of bandwidth authorities, but if no bandwidth authorities are running (as on a test network), we might fall back either to relays’ self-declared values, or we might treat all relays as having equal bandwidth.)
• The role that we’re selecting a relay to play. (See WeightRole).
• The flags that a relay has in the consensus, and their scarcity. If a relay provides particularly scarce functionality, we might choose not to use it for other roles, or to use it less commonly for them.

Structs

RelayWeight 🔒

Description for how to weight a single kind of relay for each WeightRole.

WeightKind 🔒

A kind of relay, for the purposes of selecting a relay by weight.

WeightSet 🔒

Information derived from a consensus to use when picking relays by weighted bandwidth.

Enums

BandwidthFn 🔒

Internal: how should we find the base bandwidth of each relay? This value is global over a whole directory, and depends on the bandwidth weights in the consensus.

WeightRole

Possible ways to weight relays when selecting them a random.

Constants

DFLT_WEIGHT 🔒

The value to return if a weight parameter is absent.

Functions

calculate_shift 🔒

Compute a ‘shift’ value such that (a * b) >> shift will be contained inside 64 bits.

clamp_to_pos 🔒

If inp is less than 0, return 0. Otherwise return inp as a u32.

log2_upper 🔒

Return an upper bound for the log2 of n.

pick_bandwidth_fn 🔒

Helper: Calculate the function we should use to find initial relay bandwidths.

w_param 🔒

Return the weight param named ‘kwd’ in p.