Struct NetworkCoordinate

Source

pub struct NetworkCoordinate<const N: usize> { /* private fields */ }

Expand description

A NetworkCoordinate<N> is the main interface to a Vivaldi network coordinate.

§Generic Parameters

N: Const generic for number of dimensions. For example, NetworkCoordinate<3> is a 3-Dimentionsal Euclidean coordinate plus a height. Should be a positive number greater than zero.

Note: Dimensions other than 2D or 3D are usually not useful. If you want to use one of those dimensions, you can use type aliases (NetworkCoordinate2D or NetworkCoordinate3D) which are a little more ergonomic than using the generic here.

§Examples

For an explanation and examples of usage, please see the main crate documentation.

Implementations§

Source §

impl<const N: usize> NetworkCoordinate<N>

Source

pub fn new() -> Self

Creates a new random NetworkCoordinate

§Example

use vivaldi_nc::NetworkCoordinate;

// create a new 3-dimensional random NC
let a: NetworkCoordinate<3> = NetworkCoordinate::new();

// print the NC
println!("Our new NC is: {:#?}", a);

Source

pub fn estimated_rtt(&self, rhs: &Self) -> Duration

Given another Vivaldi NetworkCoordinate, estimate the round trip time (ie ping) between them.

This is done by computing the height vector distance between between the two coordinates. Vivaldi uses this distance as a representation of estimated round trip time.

§Parameters

rhs: the other coordinate

§Returns

the estimated round trip time as a Duration

§Example

use vivaldi_nc::NetworkCoordinate;

// create some 2-dimensional NCs for the sake of this example. These will just be random
// NCs. In a real usecase these would have meaningful values.
let a: NetworkCoordinate<2> = NetworkCoordinate::new();
let b: NetworkCoordinate<2> = NetworkCoordinate::new();

// get the estimated RTT, convert to milliseconds, and print
println!("Estimated RTT: {}", a.estimated_rtt(&b).as_millis());

Source

pub fn update(&mut self, rhs: &Self, rtt: Duration) -> &Self

Given another Vivaldi NetworkCoordinate, adjust our coordinateto better represent the actual round trip time (aka distance) between us.

§Parameters

rhs: the other coordinate
rtt: the measured round trip time between self and rhs

§Returns

a reference to self

§Example

use core::time::Duration;
use vivaldi_nc::NetworkCoordinate;

// We always have our own NC:
let mut local: NetworkCoordinate<2> = NetworkCoordinate::new();

// Assume we received a NC from a remote node:
let remote: NetworkCoordinate<2> = NetworkCoordinate::new();

// And we measured the RTT between us and the remote node:
let rtt = Duration::from_millis(100);

// Now we can update our NC to adjust our position relative to the remote node:
local.update(&remote, rtt);

§Algorithm

This is an implementation of Vivaldi NCs per the original paper. It implements the following alogirthm (quoting from paper):

// Incorporate new information: node j has been
// measured to be rtt ms away, has coordinates xj,
// and an error estimate of ej .
//
// Our own coordinates and error estimate are xi and ei.
//
// The constants ce and cc are tuning parameters.

vivaldi(rtt, xj, ej)
    // Sample weight balances local and remote error. (1)
    w = ei /(ei + ej)
    // Compute relative error of this sample. (2)
    es = ∣∣∣‖xi − xj‖ − rtt∣∣∣/rtt
    // Update weighted moving average of local error. (3)
    ei = es × ce × w + ei × (1 − ce × w)
    // Update local coordinates. (4)
    δ = cc × w
    xi = xi + δ × (rtt − ‖xi − xj ‖) × u(xi − xj)

Source