Trait foca::BroadcastHandler

source · 
pub trait BroadcastHandler<T> {
    type Key: Invalidates;
    type Error: Debug + Display + Send + Sync + 'static;

    // Required method
    fn receive_item(
        &mut self,
        data: &[u8],
        sender: Option<&T>
    ) -> Result<Option<Self::Key>, Self::Error>;

    // Provided method
    fn should_add_broadcast_data(&self, _member: &T) -> bool { ... }
}
Expand description

A type capable of decoding a (associated) broadcast from a buffer and deciding whether to keep disseminating it for other members of the cluster (when it’s new information) or to discard it (when its outdated/stale).

Required Associated Types§

source

type Key: Invalidates

A unique identifier for the broadcasts this handler manages

It should be able to compare itself against an arbitrary number of other Self::Key instances and decide wether it replaces it or not so conflicting/stale information isn’t disseminated.

source

type Error: Debug + Display + Send + Sync + 'static

The error type that receive_item may emit. Will be wrapped by crate::Error::CustomBroadcast.

Required Methods§

source

fn receive_item( &mut self, data: &[u8], sender: Option<&T> ) -> Result<Option<Self::Key>, Self::Error>

Decodes a Self::Key from a buffer and either discards it or tells Foca to persist and disseminate it.

Sender is None when you’re adding broadcast data directly, via crate::Foca::add_broadcast, otherwise it will be the address of the member that sent the data. Notice that Foca doesn’t track the origin of packets- if you need it you have to add it to the data you’re broadcasting.

When you receive a broadcast you have to decide whether it’s new information that needs to be disseminated (Ok(Some(...))) or not (Ok(None)).

Always yielding Some(...) is wrong because Foca will never know when to stop sending this information to other members.

Example: Assume your custom broadcast is a simple Set-Key-Value operation. When you receive it you should check if your map contains the Key-Value pair; If it didn’t, you yield Some, otherwise the operation is stale, so you yield None.

The data parameter is the exact data provided to crate::Foca::add_broadcast. When Foca receives N custom broadcasts at once, this gets called N times.

Provided Methods§

source

fn should_add_broadcast_data(&self, _member: &T) -> bool

Decides whether Foca should add broadcast data to the message it’s about to send to active member T.

Normally when Foca sends a message it always tries to include custom broadcasts alongside the information it actually cares about; This allows implementations to override this logic with something else.

Example: You are running a heterogeneous cluster and some nodes are always very busy and you’d rather they never have to deal with the extra cpu/bandwidth cost of receiving/sending your custom broadcasts.

Returning true tells Foca to proceed as it would normally, including broadcasts in the messages it sends when it can.

Returning false tells Foca to not include such broadcasts in the message. It does not prevent the message from being sent, just keeps Foca from attaching extra data to them.

Implementors§