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§
sourcetype Key: Invalidates
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.
Required Methods§
sourcefn receive_item(
&mut self,
data: &[u8],
sender: Option<&T>
) -> Result<Option<Self::Key>, Self::Error>
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§
sourcefn should_add_broadcast_data(&self, _member: &T) -> bool
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.