Struct libp2p::Swarm

pub struct Swarm<TBehaviour>
where
    TBehaviour: NetworkBehaviour,
{ /* private fields */ }

Contains the state of the network, plus the way it should behave.

Note: Needs to be polled via <Swarm as Stream> in order to make progress.

Implementations

impl<TBehaviour> Swarm<TBehaviour>

where TBehaviour: NetworkBehaviour,

pub fn new( transport: Boxed<(PeerId, StreamMuxerBox)>, behaviour: TBehaviour, local_peer_id: PeerId, config: Config ) -> Swarm<TBehaviour>

Creates a new Swarm from the given Transport, NetworkBehaviour, PeerId and Config.

pub fn network_info(&self) -> NetworkInfo

Returns information about the connections underlying the Swarm.

pub fn listen_on( &mut self, addr: Multiaddr ) -> Result<ListenerId, TransportError<Error>>

Starts listening on the given address. Returns an error if the address is not supported.

Listeners report their new listening addresses as SwarmEvent::NewListenAddr. Depending on the underlying transport, one listener may have multiple listening addresses.

pub fn remove_listener(&mut self, listener_id: ListenerId) -> bool

Remove some listener.

Returns true if there was a listener with this ID, false otherwise.

pub fn dial(&mut self, opts: impl Into<DialOpts>) -> Result<(), DialError>

Dial a known or unknown peer.

See also DialOpts.

let mut swarm = build_swarm();

// Dial a known peer.
swarm.dial(PeerId::random());

// Dial an unknown peer.
swarm.dial("/ip6/::1/tcp/12345".parse::<Multiaddr>().unwrap());

pub fn listeners(&self) -> impl Iterator<Item = &Multiaddr>

Returns an iterator that produces the list of addresses we’re listening on.

pub fn local_peer_id(&self) -> &PeerId

Returns the peer ID of the swarm passed as parameter.

pub fn external_addresses(&self) -> impl Iterator<Item = &Multiaddr>

List all confirmed external address for the local node.

pub fn add_external_address(&mut self, a: Multiaddr)

Add a confirmed external address for the local node.

This function should only be called with addresses that are guaranteed to be reachable. The address is broadcast to all NetworkBehaviours via FromSwarm::ExternalAddrConfirmed.

pub fn remove_external_address(&mut self, addr: &Multiaddr)

Remove an external address for the local node.

The address is broadcast to all NetworkBehaviours via FromSwarm::ExternalAddrExpired.

pub fn add_peer_address(&mut self, peer_id: PeerId, addr: Multiaddr)

Add a new external address of a remote peer.

The address is broadcast to all NetworkBehaviours via FromSwarm::NewExternalAddrOfPeer.

pub fn disconnect_peer_id(&mut self, peer_id: PeerId) -> Result<(), ()>

Disconnects a peer by its peer ID, closing all connections to said peer.

Returns Ok(()) if there was one or more established connections to the peer.

Closing a connection via Swarm::disconnect_peer_id will poll ConnectionHandler::poll_close to completion. Use this function if you want to close a connection despite it still being in use by one or more handlers.

pub fn close_connection(&mut self, connection_id: ConnectionId) -> bool

Attempt to gracefully close a connection.

Closing a connection is asynchronous but this function will return immediately. A SwarmEvent::ConnectionClosed event will be emitted once the connection is actually closed.

Returns

• true if the connection was established and is now being closed.
• false if the connection was not found or is no longer established.

pub fn is_connected(&self, peer_id: &PeerId) -> bool

Checks whether there is an established connection to a peer.

pub fn connected_peers(&self) -> impl Iterator<Item = &PeerId>

Returns the currently connected peers.

pub fn behaviour(&self) -> &TBehaviour

Returns a reference to the provided NetworkBehaviour.

pub fn behaviour_mut(&mut self) -> &mut TBehaviour

Returns a mutable reference to the provided NetworkBehaviour.

Trait Implementations

impl<TBehaviour> FusedStream for Swarm<TBehaviour>

where TBehaviour: NetworkBehaviour,

The stream of swarm events never terminates, so we can implement fused for it.

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl<TBehaviour> Stream for Swarm<TBehaviour>

where TBehaviour: NetworkBehaviour,

Stream of events returned by Swarm.

Includes events from the NetworkBehaviour as well as events about connection and listener status. See SwarmEvent for details.

Note: This stream is infinite and it is guaranteed that [futures::Stream::poll_next] will never return Poll::Ready(None).

type Item = SwarmEvent<<TBehaviour as NetworkBehaviour>::ToSwarm>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Swarm<TBehaviour>>, cx: &mut Context<'_> ) -> Poll<Option<<Swarm<TBehaviour> as Stream>::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<TBehaviour> Unpin for Swarm<TBehaviour>

where TBehaviour: NetworkBehaviour,