Trait Isolation

Source

pub trait Isolation:
    Sealed
    + Downcast
    + DynClone
    + Debug
    + Send
    + Sync
    + 'static {
    // Required methods
    fn compatible(&self, other: &dyn Isolation) -> bool;
    fn join(&self, other: &dyn Isolation) -> Option<Box<dyn Isolation>>;

    // Provided method
    fn enables_long_lived_circuits(&self) -> bool { ... }
}

Expand description

A type that can make isolation decisions about streams it is attached to.

Types that implement Isolation contain properties about a stream that are used to make decisions about whether that stream can share the same circuit as other streams. You may pass in any type implementing Isolation when creating a stream via TorClient::connect_with_prefs, or constructing a circuit with CircMgr::get_or_launch_exit().

You typically do not want to implement this trait directly. Instead, most users should implement IsolationHelper.

Required Methods§

Source

fn compatible(&self, other: &dyn Isolation) -> bool

Return true if this Isolation is compatible with another.

Two streams may share a circuit if and only if they have compatible Isolations.

§Requirements

For correctness, this relation must be symmetrical and reflexive: self.compatible(other) must equal other.compatible(self), and self.compatible(self) must be true.

For correctness, this function must always give the same result as self.join(other).is_some().

This relationship does not have to be transitive: it’s possible that stream A can share a circuit with either stream B or stream C, but not with both.

Source

fn join(&self, other: &dyn Isolation) -> Option<Box<dyn Isolation>>

Join two Isolation into the intersection of what each allows.

A circuit’s isolation is the join of the isolation values of all of the streams that have ever used that circuit. A circuit’s isolation can never be None: streams that would cause it to be None can’t be attached to the circuit.

When a stream is added to a circuit, join is used to calculate the circuit’s new isolation.

§Requirements

For correctness, this function must be commutative: self.join(other) must equal other.join(self). Also, it must be idempotent: self.join(self) must equal self.

Provided Methods§

Source

fn enables_long_lived_circuits(&self) -> bool

Return true if this Isolation object should be considered sufficiently strong as to enable long-lived circuits.

By default, once a circuit has been in use for long enough, it is considered no longer usable for new circuits. But if the circuit’s isolation is sufficiently strong (and this method returns true) then a circuit will keep being used for new streams indefinitely.

The default implementation of this method returns false.