Struct kitsune_p2p_dht::arq::Arq

pub struct Arq<S: ArqStart = Loc> {
    pub start: S,
    pub power: u8,
    pub count: SpaceOffset,
}

A quantized DHT arc.

Coordinates

Arq coordinates are expressed in terms of powers-of-two, representing the “chunk” or “segment” size to work with. The chunk size is determined by the Topology of the space it is in, as well as the power of the Arq. The actual chunk size is given by:

chunk size = topology.space.quantum * 2^power

So, the power represents the amount of quantization on top of the quantum size set by the Topology, not the total quantization level.

The start is generic, because there are actually two flavors of Arq:

• one which has a definite starting DhtLocation associated with it,
• and one which does not.

The first flavor is used to represent Arqs which belong to Agents. It’s important to record the actual absolute Location of the Arq, because the exact location determines the starting Chunk when requantizing to higher and lower levels.

The second flavor is mainly used to represent the intersections and unions of Arqs. In this case, there is no definite location associated, so we want to forget about the original Location data associated with each Arq.

Fields

start: S

The “start” defines the left edge of the arq

power: u8

The level of quantization. Total length is 2^power * count. The power must be between 0 and 31, inclusive (power of 32 causes overflow)

count: SpaceOffset

The number of unit lengths. We never expect the count to be less than 4 or so, and not much larger than 32.

Implementations

impl<S: ArqStart> Arq<S>

pub fn to_ascii(&self, topo: &Topology, len: usize) -> String

Handy ascii representation of an arc, especially useful when looking at several arcs at once to get a sense of their overlap

impl<S: ArqStart> Arq<S>

pub fn new(power: u8, start: S, count: SpaceOffset) -> Self

Constructor from individual parts

pub fn absolute_length(&self, topo: &Topology) -> u64

The absolute length of the entire arq.

pub fn to_dht_arc_range(&self, topo: &Topology) -> DhtArcRange

Convert to DhtArcRange

pub fn to_edge_locs(&self, topo: &Topology) -> (Loc, Loc)

Determine the edges of this Arq in absolute coordinates (Loc)

pub fn power(&self) -> u8

Accessor

pub fn count(&self) -> u32

Accessor

pub fn coverage(&self, topo: &Topology) -> f64

What portion of the whole circle does this arq cover?

pub fn requantize(&self, new_power: u8) -> Option<Self>

Requantize to a different power. If requantizing to a higher power, only requantize if there is no information loss due to rounding. Otherwise, return None.

pub fn is_full(&self, topo: &Topology) -> bool

This arq has full coverage

pub fn is_empty(&self) -> bool

This arq has zero coverage

impl Arq<Loc>

pub fn new_full(topo: &Topology, start: Loc, power: u8) -> Self

Construct a full arq at the given power. The count is calculated accordingly.

pub fn downshift(&self) -> Self

Reduce the power by 1

pub fn upshift(&self, force: bool) -> Option<Self>

Increase the power by 1. If this results in rounding, return None, unless force is true, in which case always return Some.

pub fn to_bounds(&self, topo: &Topology) -> ArqBounds

Convert to the ArqBounds representation, which forgets about the Loc associated with this arq.

pub fn start_loc(&self) -> Loc

Get a reference to the arq’s left edge in absolute coordinates.

pub fn count_mut(&mut self) -> &mut u32

Get a mutable reference to the arq’s count.

pub fn to_dht_arc(&self, topo: &Topology) -> DhtArc

Convert to DhtArc

pub fn from_dht_arc_approximate( topo: &Topology, strat: &ArqStrat, dht_arc: &DhtArc ) -> Self

Computes the Arq which most closely matches the given DhtArc

pub fn equivalent(topo: &Topology, a: &Self, b: &Self) -> bool

The two arqs represent the same interval despite having potentially different terms

impl Arq<SpaceOffset>

pub fn equivalent(topo: &Topology, a: &Self, b: &Self) -> bool

The two arqs represent the same interval despite having potentially different terms

pub fn from_interval_rounded( topo: &Topology, power: u8, interval: DhtArcRange ) -> (Self, bool)

Return the ArqBounds which most closely matches the given DhtArcRange

pub fn from_interval( topo: &Topology, power: u8, interval: DhtArcRange ) -> Option<Self>

Return the ArqBounds which is equivalent to the given DhtArcRange if it exists.

pub fn to_arq<F: FnOnce(Loc) -> Loc>(&self, topo: &Topology, f: F) -> Arq

Upcast this ArqBounds to an Arq that has knowledge of its Loc

pub fn empty(topo: &Topology, power: u8) -> Self

An arbitrary zero-coverage arq.

pub fn segments(&self) -> impl Iterator<Item = SpaceSegment> + '_

Iterate over each segment (chunk) in the Arq

pub fn offset(&self) -> SpaceOffset

Get a reference to the arq bounds’s offset.

Trait Implementations

impl<S: Clone + ArqStart> Clone for Arq<S>

fn clone(&self) -> Arq<S>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: Debug + ArqStart> Debug for Arq<S>

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

Formats the value using the given formatter.

impl<'de, S> Deserialize<'de> for Arq<S>

where S: Deserialize<'de> + ArqStart,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&Arq<SpaceOffset>> for ArqBounds

fn from(a: &ArqBounds) -> Self

Converts to this type from the input type.

impl<S: PartialEq + ArqStart> PartialEq for Arq<S>

fn eq(&self, other: &Arq<S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S> Serialize for Arq<S>

where S: Serialize + ArqStart,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<S: Copy + ArqStart> Copy for Arq<S>

impl<S: Eq + ArqStart> Eq for Arq<S>

impl<S: ArqStart> StructuralPartialEq for Arq<S>