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 new(power: u8, start: S, count: SpaceOffset) -> Self

Constructor from individual parts

pub fn absolute_length(&self, dim: impl SpaceDim) -> u64

The absolute length of the entire arq.

pub fn to_dht_arc_range_std(&self) -> DhtArcRange

Convert to DhtArcRange using standard topology

pub fn to_dht_arc_range(&self, dim: impl SpaceDim) -> DhtArcRange

Convert to DhtArcRange

pub fn to_edge_locs(&self, dim: impl SpaceDim) -> (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, dim: impl SpaceDim) -> 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 new_full(dim: impl SpaceDim, start: S, power: u8) -> Self

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

pub fn new_full_max(dim: impl SpaceDim, strat: &ArqStrat, start: S) -> Self

Construct a full arq at the maximum power.

pub fn is_full(&self, dim: impl SpaceDim) -> bool

This arq has full coverage

pub fn is_empty(&self) -> bool

This arq has zero coverage

impl Arq<Loc>

pub fn new_empty(dim: impl SpaceDim, start: Loc) -> Self

Construct an empty arq (count = 0) at the minimum power.

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_std(&self) -> ArqBounds

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

pub fn to_bounds(&self, dim: impl SpaceDim) -> 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, dim: impl SpaceDim) -> DhtArc

Convert to DhtArc

pub fn to_dht_arc_std(&self) -> DhtArc

Convert to DhtArc using the standard SpaceDimension

pub fn from_dht_arc_approximate( dim: impl SpaceDim, strat: &ArqStrat, dht_arc: &DhtArc ) -> Self

Computes the Arq which most closely matches the given DhtArc

pub fn equivalent(dim: impl SpaceDim, a: &Self, b: &Self) -> bool

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

pub fn from_start_and_half_len_approximate( dim: impl SpaceDim, strat: &ArqStrat, start: Loc, half_len: u32 ) -> Self

Computes the Arq which most closely matches the given params

impl Arq<SpaceOffset>

pub fn equivalent(dim: impl SpaceDim, a: &Self, b: &Self) -> bool

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

pub fn from_interval_rounded( dim: impl SpaceDim, power: u8, interval: DhtArcRange ) -> (Self, bool)

Return the ArqBounds which most closely matches the given DhtArcRange

pub fn from_interval( dim: impl SpaceDim, power: u8, interval: DhtArcRange ) -> Option<Self>

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

pub fn empty(dim: impl SpaceDim, 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 From<Arq> for ArqSize

fn from(arq: Arq) -> Self

Converts to this type from the input type.

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

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

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>