Struct instance_chart::ChartBuilder

pub struct ChartBuilder<const N: usize, IdSet, PortSet, PortsSet>where
    IdSet: ToAssign,
    PortSet: ToAssign,
    PortsSet: ToAssign,{ /* private fields */ }

Construct a Chart using a builder-like pattern. You must always set an id. You also need to set service port or service ports. Now you can build with finish or using custom_msg. The latter allowes you to set a custom message to share with other instances when they discover you.

Implementations

impl<const N: usize> ChartBuilder<N, No, No, No>

pub fn new() -> ChartBuilder<N, No, No, No>

Create a new chart builder

impl<const N: usize, IdSet, PortSet, PortsSet> ChartBuilder<N, IdSet, PortSet, PortsSet>where IdSet: ToAssign, PortSet: ToAssign, PortsSet: ToAssign,

pub fn with_id(self, id: Id) -> ChartBuilder<N, Yes, PortSet, PortsSet>

Set the Id for this node, the Id is the key for this node in the chart

Note

Always needed, you can not build without an Id set. The Id must be unique

pub fn with_random_id(self) -> ChartBuilder<N, Yes, PortSet, PortsSet>

Use a true random number from a reliable source of randomness as an Id.

Note

I recommend setting the Id in a deterministic way if possible, it makes debugging a lot easier. Theoretically using this method can fail if multiple instances get the same random number, the chance of this is unrealistically small.

It is extreemly unlikely though possible that this fails. This happens if the systems source of random is configured incorrectly.

pub fn with_service_port(self, port: u16) -> ChartBuilder<N, IdSet, Yes, No>

Set a port for use by your application. This will appear to the other nodes in the Chart.

Note

You need to use this or with_service_ports if building with finish(). Cant be used when bulding with custom_msg.

pub fn with_service_ports( self, ports: [u16; N] ) -> ChartBuilder<N, IdSet, No, Yes>

Set mutiple ports for use by your application. This will appear to the other nodes in the Chart.

Note

You need to use this or with_service_port if building with finish(). Cant be used when bulding with custom_msg.

pub fn with_header( self, header: u64 ) -> ChartBuilder<N, IdSet, PortSet, PortsSet>

set a custom header number. The header is used to identify your application’s chart from others multicast traffic when deployed your should set this to a random number.

pub fn with_discovery_port( self, port: u16 ) -> ChartBuilder<N, IdSet, PortSet, PortsSet>

set custom port for discovery. With [local discovery] enabled this port needs to be free and unused on all nodes it is not free the multicast traffic caused by this library might corrupt network data of other applications. The default port is 8080.

Warning

Not all ports seem to pass multicast traffic, you might need to experiment a bit.

pub fn with_rampdown( self, min: Duration, max: Duration, rampdown: Duration ) -> ChartBuilder<N, IdSet, PortSet, PortsSet>

set duration between discovery broadcasts, decreases linearly from max to min over rampdown period.

Panics

panics if min is larger then max

pub fn local_discovery( self, is_enabled: bool ) -> ChartBuilder<N, IdSet, PortSet, PortsSet>

set whether discovery is enabled within the same host. Defaults to false.

Warning

When this is enabled you might not be warned if the discovery port is in use by another application. The other application will recieve network traffic from this crate. This might lead to corruption in the application if it can not handle this. ChartBuilder will still fail if the discovery port is already bound to a multicast adress without SO_REUSEADDR set.

impl ChartBuilder<1, Yes, No, No>

pub fn custom_msg<Msg>(self, msg: Msg) -> Result<Chart<1, Msg>, Error>where Msg: Debug + Serialize + Clone,

build a chart with a custom msg instead of a service port. The message can be any struct that implements Debug, Clone, serde::Serialize and serde::Deserialize

Errors

This errors if the discovery port could not be opened. see: Self::with_discovery_port.

Example

use instance_chart::{discovery, ChartBuilder};
use serde::{Serialize, Deserialize};
use std::error::Error;
use std::time::Duration;

#[derive(Debug, Clone, Serialize, Deserialize)]
struct Msg(u32);

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
  let msg = Msg(0);
  let chart = ChartBuilder::new()
      .with_id(1)
      .with_discovery_port(8888)
      .with_header(17249479) // optional
      .with_rampdown( // optional
          Duration::from_millis(10),
          Duration::from_secs(10),
          Duration::from_secs(60))
      .custom_msg(msg)?;
  let maintain = discovery::maintain(chart.clone());
  let _ = tokio::spawn(maintain); // maintain task will run forever
  Ok(())
}

impl ChartBuilder<1, Yes, Yes, No>

pub fn finish(self) -> Result<Chart<1, u16>, Error>

build a chart that has a single service ports set

Errors

This errors if the discovery port could not be opened. see: Self::with_discovery_port.

Example

use std::error::Error;
use instance_chart::{discovery, ChartBuilder};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
  let chart = ChartBuilder::new()
      .with_id(1)
      .with_service_port(8042)
      .with_discovery_port(8888)
      .with_header(17249479) // optional
      .with_rampdown( // optional
          Duration::from_millis(10),
          Duration::from_secs(10),
          Duration::from_secs(60))
      .finish()?;
  let maintain = discovery::maintain(chart.clone());
  let _ = tokio::spawn(maintain); // maintain task will run forever
  Ok(())
}

impl<const N: usize> ChartBuilder<N, Yes, No, Yes>

pub fn finish(self) -> Result<Chart<N, u16>, Error>

build a chart that has a multiple service ports set

Errors

This errors if the discovery port could not be opened. see: Self::with_discovery_port.

Example

use std::error::Error;
use instance_chart::{discovery, ChartBuilder};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
  let chart = ChartBuilder::new()
      .with_id(1)
      .with_service_ports([8042,9042])
      .with_discovery_port(8888)
      .with_header(17249479) // optional
      .with_rampdown( // optional
          Duration::from_millis(10),
          Duration::from_secs(10),
          Duration::from_secs(60))
      .finish()?;
  let maintain = discovery::maintain(chart.clone());
  let _ = tokio::spawn(maintain); // maintain task will run forever
  Ok(())
}