Struct Foca 

pub struct Foca<T: Identity, C, RNG, B: BroadcastHandler<T>> { /* private fields */ }

Foca is the main interaction point of this crate.

It manages the cluster members and executes the SWIM protocol. It’s intended as a low-level guts-exposed safe view into the protocol allowing any kind of Identity and transport to be used.

Most interactions with Foca require the caller to provide a Runtime type, which is simply a way to turn the result of an operation inside out (think callbacks, or an out parameter like void* out). This allows Foca to avoid deciding anything related to how it interacts with the operating system.

Implementations

impl<T, C, RNG> Foca<T, C, RNG, NoCustomBroadcast>

where T: Identity, C: Codec<T>, C::Error: Error + Send, RNG: Rng,

pub fn new(identity: T, config: Config, rng: RNG, codec: C) -> Self

Create a new Foca instance with custom broadcasts disabled.

This is a simple shortcut for Foca::with_custom_broadcast using the NoCustomBroadcast type to deny any form of custom broadcast.

impl<T, C, RNG, B> Foca<T, C, RNG, B>

where T: Identity, C: Codec<T>, C::Error: Error, RNG: Rng, B: BroadcastHandler<T>, B::Error: Error + 'static,

pub fn with_custom_broadcast( identity: T, config: Config, rng: RNG, codec: C, broadcast_handler: B, ) -> Self

Initialize a new Foca instance.

pub fn identity(&self) -> &T

Getter for the current identity.

pub fn reuse_down_identity(&mut self) -> Result<(), Error>

Re-enable joining a cluster with the same identity after being declared Down.

This is intended to be use by implementations that decide not to opt-in on auto-rejoining: once Foca detects its Down you’ll only be able to receive messages (which will likely stop after a short while since the cluster things you are down).

Whatever is controlling the running Foca will then have to wait for at least Config::remove_down_after before attempting a rejoin. Then you can call this method followed by a [Foca::announce(T)] to go back to the cluster.

pub fn change_identity( &mut self, new_id: T, runtime: impl Runtime<T>, ) -> Result<(), Error>

Change the current identity.

Foca will declare its previous identity as Down and immediatelly notify the cluster about the changes.

Notice that changing your identity does not guarantee a successful (re)join. After changing it and disseminating the updates Foca will only know it’s actually accepted after receiving a message addressed to it.

Watch for Notification::Active if you want more confidence about a successful (re)join.

Intended to be used when identities carry metadata that occasionally changes.

pub fn iter_members(&self) -> impl Iterator<Item = &Member<T>>

Iterate over the currently active cluster members.

pub fn num_members(&self) -> usize

Returns the number of active members in the cluster.

May only be used as a bound for Foca::iter_members if no Foca method that takes &mut self is called in-between.

pub fn iter_membership_state(&self) -> impl ExactSizeIterator<Item = &Member<T>>

Iterates over the full membership state, including members that have been declared down.

This is for advanced usage, to be used in tandem with Foca::apply_many. The main use-case for this is state replication:

1. You may want to send it to another node so that it knows all you do; if said member sends you their state as an immediate reply, both states will be exactly the same. The reply can be a lot smaller than the full state in most cases, if payload size if a concern.

2. You might want to save the full state to disk before restarting a process running Foca so that you can get back up quickly with low risk of accepting stale knowledge as truthful

pub fn apply_many( &mut self, updates: impl Iterator<Item = Member<T>>, do_broadcast: bool, runtime: impl Runtime<T>, ) -> Result<(), Error>

Applies cluster updates to this foca instance.

This is for advanced usage. It’s intended as a way to unlock more elaborate synchronization protocols: implementations may choose to unify their cluster knowledge (say: a streaming join protocol or a periodic sync) and use Foca::apply_many as a way to feed Foca this new (external) knowledge.

The do_broadcast parameter flags wether the updates should shared with cluster (when relevant). In general, true is the correct value. Not broadcasting is useful when you’re restoring knowledge after going offline and you don’t want to broadcast data that you know (or rather: assume) the rest of the cluster already knows about.

pub fn announce( &mut self, dst: T, runtime: impl Runtime<T>, ) -> Result<(), Error>

Attempt to join the cluster dst belongs to.

Sends a Message::Announce to dst. If accepted, we’ll receive a Message::Feed as reply.

pub fn gossip(&mut self, runtime: impl Runtime<T>) -> Result<(), Error>

Disseminate updates/broadcasts to cluster members.

This instructs Foca to pick Config::num_indirect_probes random active members and send a Message::Gossip containing cluster updates.

Intended for more complex scenarios where an implementation wants to attempt reducing the time it takes for information to propagate thoroughly.

pub fn broadcast(&mut self, runtime: impl Runtime<T>) -> Result<(), Error>

Only disseminate custom broadcasts to cluster members

This instructs Foca to pick Config::num_indirect_probes random active members that pass the BroadcastHandler::should_add_broadcast_data check. It guarantees custom broadcast dissemination if there are candidate members available.

No cluster update will be sent with these messages. Intended to be used in tandem with a non-default should_add_broadcast_data.

pub fn leave_cluster(&mut self, runtime: impl Runtime<T>) -> Result<(), Error>

Leave the cluster by declaring our own identity as down.

If there are active members, a few are selected and notified of our exit so that the cluster learns about it quickly.

This is the cleanest way to terminate a running Foca.

pub fn add_broadcast(&mut self, data: &[u8]) -> Result<bool, Error>

Register some data to be broadcast along with Foca messages.

Calls into this instance’s BroadcastHandler and reacts accordingly.

pub fn handle_timer( &mut self, event: Timer<T>, runtime: impl Runtime<T>, ) -> Result<(), Error>

React to a previously scheduled timer event.

See Runtime::submit_after.

pub fn updates_backlog(&self) -> usize

Reports the current length of the cluster updates queue.

Updates are transmitted Config::max_transmissions times at most or until we learn new information about the same member.

pub fn custom_broadcast_backlog(&self) -> usize

Reports the current length of the custom broadcast queue.

Custom broadcasts are transmitted Config::max_transmissions times at most or until they get invalidated by another custom broadcast.

pub fn set_config(&mut self, config: Config) -> Result<(), Error>

Replaces the current configuration with a new one.

Most of the time a static configuration is more than enough, but for use-cases where the cluster size can drastically change during normal operations, changing the configuration parameters is a nicer alternative to recreating the Foca instance.

Changing Config::probe_period, Config::probe_rtt or trying to enable any periodic_ setting results in Error::InvalidConfig; For such cases it’s recommended to recreate your Foca instance.

When an error occurs, every configuration parameter remains unchanged.

pub fn handle_data( &mut self, data: &[u8], runtime: impl Runtime<T>, ) -> Result<(), Error>

Handle data received from the network.

Data larger than the configured limit will be rejected. Errors are expected if you’re receiving arbitrary data (which very likely if you are listening to a socket address).

Trait Implementations

impl<T, C, RNG, B> Debug for Foca<T, C, RNG, B>

where T: Identity, B: BroadcastHandler<T>,

Available on crate feature tracing only.

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

Formats the value using the given formatter.