Struct Memberlist 

pub struct Memberlist<T, D = VoidDelegate<<T as Transport>::Id, <<T as Transport>::Resolver as AddressResolver>::ResolvedAddress>>
where
    D: Delegate<Id = T::Id, Address = T::ResolvedAddress>,
    T: Transport,
{ /* private fields */ }

A cluster membership and member failure detection using a gossip based protocol.

The use cases for such a library are far-reaching: all distributed systems require membership, and memberlist is a re-usable solution to managing cluster membership and node failure detection.

memberlist is eventually consistent but converges quickly on average. The speed at which it converges can be heavily tuned via various knobs on the protocol. Node failures are detected and network partitions are partially tolerated by attempting to communicate to potentially dead nodes through multiple routes.

Implementations

impl<T, D> Memberlist<T, D>

where D: Delegate<Id = T::Id, Address = T::ResolvedAddress>, T: Transport,

pub fn local_id(&self) -> &T::Id

Returns the local node ID.

pub fn local_address(&self) -> &<T::Resolver as AddressResolver>::Address

Returns the local node address

pub fn advertise_node(&self) -> Node<T::Id, T::ResolvedAddress>

Returns a Node with the local id and the advertise address of local node.

pub fn advertise_address(&self) -> &T::ResolvedAddress

Returns the advertise address of local node.

pub fn keyring(&self) -> Option<&Keyring>

Available on crate feature encryption only.

Returns the keyring (only used for encryption) of the node

pub fn encryption_enabled(&self) -> bool

Available on crate feature encryption only.

Returns true if the node enables encryption.

pub fn delegate(&self) -> Option<&D>

Returns the delegate, if any.

pub async fn local_state( &self, ) -> Option<Arc<NodeState<T::Id, T::ResolvedAddress>>>

Returns the local node instance state.

pub async fn by_id( &self, id: &T::Id, ) -> Option<Arc<NodeState<T::Id, T::ResolvedAddress>>>

Returns the node state of the given id. (if any).

pub async fn members( &self, ) -> SmallVec<Arc<NodeState<T::Id, T::ResolvedAddress>>>

Returns a list of all known nodes.

pub async fn num_members(&self) -> usize

Returns number of members

pub async fn online_members( &self, ) -> SmallVec<Arc<NodeState<T::Id, T::ResolvedAddress>>>

Returns a list of all known nodes that are online.

pub async fn num_online_members(&self) -> usize

Returns the number of online members.

pub async fn members_by( &self, f: impl FnMut(&NodeState<T::Id, T::ResolvedAddress>) -> bool, ) -> SmallVec<Arc<NodeState<T::Id, T::ResolvedAddress>>>

Returns a list of all known nodes that match the given predicate.

pub async fn num_members_by( &self, f: impl FnMut(&NodeState<T::Id, T::ResolvedAddress>) -> bool, ) -> usize

Returns the number of members match the given predicate.

pub async fn members_map_by<O>( &self, f: impl FnMut(&NodeState<T::Id, T::ResolvedAddress>) -> Option<O>, ) -> SmallVec<O>

Returns a list of map result on all known members that match the given predicate.

impl<T> Memberlist<T>

where T: Transport,

pub async fn new( transport_options: T::Options, opts: Options, ) -> Result<Self, Error<T, VoidDelegate<T::Id, T::ResolvedAddress>>>

Create a new memberlist with the given transport and options.

impl<T, D> Memberlist<T, D>

where D: Delegate<Id = T::Id, Address = T::ResolvedAddress>, T: Transport,

pub async fn with_delegate( delegate: D, transport_options: T::Options, opts: Options, ) -> Result<Self, Error<T, D>>

Create a new memberlist with the given transport, delegate and options.

pub async fn leave(&self, timeout: Duration) -> Result<bool, Error<T, D>>

Leave will broadcast a leave message but will not shutdown the background listeners, meaning the node will continue participating in gossip and state updates.

This will block until the leave message is successfully broadcasted to a member of the cluster, if any exist or until a specified timeout is reached.

This method is safe to call multiple times, but must not be called after the cluster is already shut down.

Returns true if the node has successfully left the cluster by this call.

pub async fn join( &self, addr: MaybeResolvedAddress<T::Address, T::ResolvedAddress>, ) -> Result<T::ResolvedAddress, Error<T, D>>

Join directly by contacting the given node address, Returns the resolved address if successfully joined, or an error if the address could not be reached.

pub async fn join_many( &self, existing: impl Iterator<Item = MaybeResolvedAddress<T::Address, T::ResolvedAddress>>, ) -> Result<SmallVec<T::ResolvedAddress>, (SmallVec<T::ResolvedAddress>, Error<T, D>)>

Used to take an existing Memberlist and attempt to join a cluster by contacting all the given hosts and performing a state sync. Initially, the Memberlist only contains our own state, so doing this will cause remote nodes to become aware of the existence of this node, effectively joining the cluster.

On success, returns a list of all addresses that were successfully joined with resolved addresses. On error, returns a list of addresses that were successfully joined with resolved addresses and the error.

pub fn health_score(&self) -> usize

Gives this instance’s idea of how well it is meeting the soft real-time requirements of the protocol. Lower numbers are better, and zero means “totally healthy”.

pub async fn update_node(&self, timeout: Duration) -> Result<(), Error<T, D>>

Used to trigger re-advertising the local node. This is primarily used with a Delegate to support dynamic updates to the local meta data. This will block until the update message is successfully broadcasted to a member of the cluster, if any exist or until a specified timeout is reached.

pub async fn send( &self, to: &T::ResolvedAddress, msg: Bytes, ) -> Result<(), Error<T, D>>

Uses the unreliable packet-oriented interface of the transport to target a user message at the given node (this does not use the gossip mechanism). The maximum size of the message depends on the configured packet_buffer_size for this memberlist instance.

See also send_reliable.

pub async fn send_many( &self, to: &T::ResolvedAddress, msgs: impl Iterator<Item = Bytes>, ) -> Result<(), Error<T, D>>

Uses the unreliable packet-oriented interface of the transport to target a user message at the given node (this does not use the gossip mechanism). The maximum size of the message depends on the configured packet_buffer_size for this memberlist instance.

pub async fn send_reliable( &self, to: &T::ResolvedAddress, msg: Bytes, ) -> Result<(), Error<T, D>>

Uses the reliable stream-oriented interface of the transport to target a user message at the given node (this does not use the gossip mechanism). Delivery is guaranteed if no error is returned, and there is no limit on the size of the message.

See also send_many_reliable.

pub async fn send_many_reliable( &self, to: &T::ResolvedAddress, msgs: impl Iterator<Item = Bytes>, ) -> Result<(), Error<T, D>>

Uses the reliable stream-oriented interface of the transport to target a user message at the given node (this does not use the gossip mechanism). Delivery is guaranteed if no error is returned, and there is no limit on the size of the message.

pub async fn ping( &self, node: Node<T::Id, T::ResolvedAddress>, ) -> Result<Duration, Error<T, D>>

Initiates a ping to the node with the specified node.

pub async fn shutdown(&self) -> Result<(), Error<T, D>>

Stop any background maintenance of network activity for this memberlist, causing it to appear “dead”. A leave message will not be broadcasted prior, so the cluster being left will have to detect this node’s shutdown using probing. If you wish to more gracefully exit the cluster, call Leave prior to shutting down.

This method is safe to call multiple times.

Trait Implementations

impl<T, D> Clone for Memberlist<T, D>

where T: Transport, D: Delegate<Id = T::Id, Address = T::ResolvedAddress>,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.