Struct Memberlist 

pub struct Memberlist<T, D = VoidDelegate<<T as Transport>::Id, <<T as Transport>::Resolver as AddressResolver>::ResolvedAddress>>
where
    D: Delegate<Id = <T as Transport>::Id, Address = <T as Transport>::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 as Transport>::Id, Address = <T as Transport>::ResolvedAddress>, T: Transport,

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

Available on crate feature tokio only.

Returns the local node ID.

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

Available on crate feature tokio only.

Returns the local node address

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

Available on crate feature tokio only.

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

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

Available on crate feature tokio only.

Returns the advertise address of local node.

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

Available on crate feature tokio only.

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

pub fn encryption_enabled(&self) -> bool

Available on crate feature tokio only.

Returns true if the node enables encryption.

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

Available on crate feature tokio only.

Returns the delegate, if any.

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

Available on crate feature tokio only.

Returns the local node instance state.

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

Available on crate feature tokio only.

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

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

Available on crate feature tokio only.

Returns a list of all known nodes.

pub async fn num_members(&self) -> usize

Available on crate feature tokio only.

Returns number of members

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

Available on crate feature tokio only.

Returns a list of all known nodes that are online.

pub async fn num_online_members(&self) -> usize

Available on crate feature tokio only.

Returns the number of online members.

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

Available on crate feature tokio only.

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

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

Available on crate feature tokio only.

Returns the number of members match the given predicate.

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

Available on crate feature tokio only.

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 as Transport>::Options, opts: Options, ) -> Result<Memberlist<T>, Error<T, VoidDelegate<<T as Transport>::Id, <T as Transport>::ResolvedAddress>>>

Available on crate feature tokio only.

Create a new memberlist with the given transport and options.

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

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

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

Available on crate feature tokio only.

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

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

Available on crate feature tokio only.

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, node: Node<<T as Transport>::Id, MaybeResolvedAddress<<T as Transport>::Address, <T as Transport>::ResolvedAddress>>, ) -> Result<Node<<T as Transport>::Id, <T as Transport>::ResolvedAddress>, Error<T, D>>

Available on crate feature tokio only.

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

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

Available on crate feature tokio only.

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 nodes that were successfully joined with resolved addresses. On error, returns a list of nodes are successfully joined with resolved addresses and the error.

pub fn health_score(&self) -> usize

Available on crate feature tokio only.

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>>

Available on crate feature tokio only.

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 as Transport>::ResolvedAddress, msg: Bytes, ) -> Result<(), Error<T, D>>

Available on crate feature tokio only.

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 as Transport>::ResolvedAddress, msgs: impl Iterator<Item = Bytes>, ) -> Result<(), Error<T, D>>

Available on crate feature tokio only.

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 as Transport>::ResolvedAddress, msg: Bytes, ) -> Result<(), Error<T, D>>

Available on crate feature tokio only.

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 as Transport>::ResolvedAddress, msgs: impl Iterator<Item = Bytes>, ) -> Result<(), Error<T, D>>

Available on crate feature tokio only.

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 as Transport>::Id, <T as Transport>::ResolvedAddress>, ) -> Result<Duration, Error<T, D>>

Available on crate feature tokio only.

Initiates a ping to the node with the specified node.

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

Available on crate feature tokio only.

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 as Transport>::Id, Address = <T as Transport>::ResolvedAddress>,

fn clone(&self) -> Memberlist<T, D>

Returns a duplicate of the value.

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

Performs copy-assignment from source.