Struct ConfluxSet 

pub(super) struct ConfluxSet {
    tunnel_id: TunnelId,
    legs: SmallVec<[Circuit; 16]>,
    mutable: Arc<TunnelMutableState>,
    primary_id: UniqId,
    join_point: Option<JoinPoint>,
    nonce: V1Nonce,
    desired_ux: V1DesiredUx,
    last_seq_delivered: Arc<AtomicU64>,
    selected_init_primary: bool,
}

A set with one or more circuits.

Conflux set life cycle

Conflux sets are created by the reactor using ConfluxSet::new.

Every ConfluxSet starts out as a single-path set consisting of a single 0-length circuit.

After constructing a ConfluxSet, the reactor will proceed to extend its (only) circuit. At this point, the ConfluxSet will be a single-path set with a single n-length circuit.

The reactor can then turn the ConfluxSet into a multi-path set (a multi-path set is a conflux set that contains more than 1 circuit). This is done using ConfluxSet::add_legs, in response to a CtrlMsg sent by the reactor user (also referred to as the “conflux handshake initiator”). After that, the conflux set is said to be a multi-path set with multiple N-length circuits.

Circuits can be removed from the set using ConfluxSet::remove.

The lifetime of a ConfluxSet is tied to the lifetime of the reactor. When the reactor is dropped, its underlying ConfluxSet is dropped too. This can happen on an explicit shutdown request, or if a fatal error occurs.

Conversely, the ConfluxSet can also trigger a reactor shutdown. For example, if after being instructed to remove a circuit from the set using ConfluxSet::remove, the set is completely depleted, the ConfluxSet will return a ReactorError::Shutdown error, which will cause the reactor to shut down.

Fields

tunnel_id: TunnelId

The unique identifier of the tunnel this conflux set belongs to.

Used for setting the internal TunnelId of Circuits that gets used for logging purposes.

legs: SmallVec<[Circuit; 16]>

The circuits in this conflux set.

mutable: Arc<TunnelMutableState>

Tunnel state, shared with ClientCirc.

Contains the MutableState of each circuit in the set.

primary_id: UniqId

The unique identifier of the primary leg

join_point: Option<JoinPoint>

The join point of the set, if this is a multi-path set.

Initially the conflux set starts out as a single-path set with no join point. When it is converted to a multipath set using add_legs, the join point is initialized to the last hop in the tunnel.

nonce: V1Nonce

The nonce associated with the circuits from this set.

desired_ux: V1DesiredUx

The desired UX

last_seq_delivered: Arc<AtomicU64>

The absolute sequence number of the last cell delivered to a stream.

A clone of this is shared with each ConfluxMsgHandler created.

When a message is received on a circuit leg, the ConfluxMsgHandler of the leg compares the (leg-local) sequence number of the message with this sequence number to determine whether the message is in-order.

If the message is in-order, the ConfluxMsgHandler instructs the circuit to deliver it to its corresponding stream.

If the message is out-of-order, the ConfluxMsgHandler instructs the circuit to instruct the reactor to buffer the message.

selected_init_primary: bool

Whether we have selected our initial primary leg, if this is a multipath conflux set.

Implementations

impl ConfluxSet

pub(super) fn new( tunnel_id: TunnelId, circuit_leg: Circuit, ) -> (Self, Arc<TunnelMutableState>)

Create a new conflux set, consisting of a single leg.

Returns the newly created set and a reference to its TunnelMutableState.

pub(super) fn take_single_leg(&mut self) -> Result<Circuit, Bug>

Remove and return the only leg of this conflux set.

Returns an error if there is more than one leg in the set, or if called before any circuit legs are available.

Calling this function will empty the ConfluxSet.

pub(super) fn single_leg(&self) -> Result<&Circuit, NotSingleLegError>

Return a reference to the only leg of this conflux set, along with the leg’s ID.

Returns an error if there is more than one leg in the set, or if called before any circuit legs are available.

pub(super) fn single_leg_mut( &mut self, ) -> Result<&mut Circuit, NotSingleLegError>

Return a mutable reference to the only leg of this conflux set, along with the leg’s ID.

Returns an error if there is more than one leg in the set, or if called before any circuit legs are available.

pub(super) fn primary_leg_mut(&mut self) -> Result<&mut Circuit, Bug>

Return the primary leg of this conflux set.

Returns an error if called before any circuit legs are available.

pub(super) fn leg(&self, leg_id: UniqId) -> Option<&Circuit>

Return a reference to the leg of this conflux set with the given id.

pub(super) fn leg_mut(&mut self, leg_id: UniqId) -> Option<&mut Circuit>

Return a mutable reference to the leg of this conflux set with the given id.

pub(super) fn len(&self) -> usize

Return the number of legs in this conflux set.

pub(super) fn is_empty(&self) -> bool

Return whether this conflux set is empty.

pub(super) fn remove(&mut self, leg: UniqId) -> Result<Circuit, ReactorError>

Remove the specified leg from this conflux set.

Returns an error if the given leg doesn’t exist in the set.

Returns an error instructing the reactor to perform a clean shutdown (ReactorError::Shutdown), tearing down the entire ConfluxSet, if

• the set is depleted (empty) after removing the specified leg
• leg is currently the sending (primary) leg of this set
• the closed leg had the highest non-zero last_seq_recv/sent
• the closed leg had some in-progress data (inflight > cc_sendme_inc)

We do not yet support resumption. See 2.4.3. Closing circuits in prop329.

fn remove_conflux(&self, circ: Circuit) -> Result<Circuit, ReactorError>

Handle the removal of a circuit, returning an error if the reactor needs to shut down.

fn max_last_seq_recv(&self) -> Option<u64>

Return the maximum relative last_seq_recv across all circuits.

fn max_last_seq_sent(&self) -> Option<u64>

Return the maximum relative last_seq_sent across all circuits.

fn join_point_hop<'c>(&self, circ: &'c Circuit) -> Result<&'c CircHop, Bug>

Get the CircHop of the join point on the specified circ, returning an error if this is a single path conflux set.

fn circuits(&self) -> impl Iterator<Item = &Circuit>

Return an iterator of all circuits in the conflux set.

pub(super) fn tunnel_activity(&self) -> TunnelActivity

Return the most active TunnelActivity for any leg of this ConfluxSet.

pub(super) fn add_legs( &mut self, legs: Vec<Circuit>, runtime: &DynTimeProvider, ) -> Result<(), Bug>

Add legs to the this conflux set.

Returns an error if any of the legs is invalid.

A leg is considered valid if

• the circuit has the same length as all the other circuits in the set
• its last hop is equal to the designated join point
• the circuit has no streams attached to any of its hops
• the circuit is not already part of a conflux set

Note: the circuits will not begin linking until link_circuits is called.

IMPORTANT: this function does not prevent the construction of conflux sets where the circuit legs share guard or middle relays. It is the responsibility of the caller to enforce the following invariant from prop354:

“If building a conflux leg: Reject any circuits that have the same Guard as the other conflux “leg(s) in the current conflux set, EXCEPT when one of the primary Guards is also the chosen “Exit of this conflux set (in which case, re-use the non-Exit Guard).”

This is because at this level we don’t actually know which relays are the guards, so we can’t know if the join point happens to be one of the Guard + Exit relays.

fn cwnd_params(&self) -> Result<CongestionWindowParams, Bug>

Get the CongestionWindowParams of the join point on the first leg.

Returns an error if the congestion control algorithm doesn’t have a congestion control window object, or if the conflux set is empty, or the joint point hop does not exist.

pub(super) fn maybe_update_primary_leg( &mut self, ) -> Result<Option<SendRelayCell>>

Try to update the primary leg based on the configured desired UX, if needed.

Returns the SWITCH cell to send on the primary leg, if we switched primary leg.

fn should_update_primary_leg(&mut self) -> bool

Whether it’s time to select a new primary leg.

fn select_primary_leg(&self) -> Result<Option<UniqId>, Bug>

Return the best leg according to the configured desired UX.

Returns None if no suitable leg was found.

fn maybe_select_init_primary(&mut self)

Try to choose an initial primary leg, if we have an initial RTT measurement for at least one of the legs.

fn select_primary_leg_min_rtt( &self, check_can_send: bool, ) -> Result<Option<UniqId>, Bug>

Return the leg with the best (lowest) RTT.

If check_can_send is true, selects the lowest RTT leg that is ready to send.

Returns None if no suitable leg was found.

fn is_join_point_blocked_on_cc( join_hop: HopNum, circuit: &Circuit, ) -> Result<bool, Bug>

Returns true if our conflux join point is blocked on congestion control on the specified circuit.

Returns false if the join point is not blocked on cc, or if this is a single-path set.

Returns an error if this is a multipath tunnel, but the joint point hop doesn’t exist on the specified circuit.

fn should_skip_join_point(&self) -> Result<bool, Bug>

Returns whether next_circ_event should avoid polling the join point streams entirely.

pub(super) async fn next_circ_event( &mut self, runtime: &DynTimeProvider, ) -> Result<SmallVec<[CircuitEvent; 32]>, Error>

Returns the next ready CircuitEvent, obtained from processing the incoming/outgoing messages on all the circuits in this set.

Will return an error if there are no circuits in this set, or other internal errors occur.

This is cancellation-safe.

pub(super) fn primary_join_point(&self) -> Option<(UniqId, HopNum)>

The join point on the current primary leg.

pub(super) fn uses_stream_sendme( &self, leg: UniqId, hop: HopNum, ) -> Option<bool>

Does congestion control use stream SENDMEs for the given hop?

Returns None if either the leg or hop don’t exist.

pub(super) async fn send_relay_cell_on_leg( &mut self, msg: SendRelayCell, leg: Option<UniqId>, ) -> Result<()>

Encode msg, encrypt it, and send it to the ’hop’th hop.

See Circuit::send_relay_cell.

pub(super) async fn link_circuits( &mut self, runtime: &DynTimeProvider, ) -> Result<()>

Send a LINK cell down each unlinked leg.

pub(super) fn num_unlinked(&self) -> usize

Get the number of unlinked or non-conflux legs.

pub(super) fn is_seqno_in_order(&self, seq_recv: u64) -> bool

Check if the specified sequence number is the sequence number of the next message we’re expecting to handle.

fn remove_unchecked(&mut self, circ_id: UniqId) -> Result<Circuit, Bug>

Remove the circuit leg with the specified UniqId from this conflux set.

Unlike ConfluxSet::remove, this function does not check if the removal of the leg ought to trigger a reactor shutdown.

Returns an error if the leg doesn’t exit in the conflux set.

pub(super) async fn run_padding_event( &mut self, circ_id: UniqId, padding_event: PaddingEvent, ) -> Result<()>

Perform some circuit-padding-based event on the specified circuit.