Struct libp2p_swarm::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
) -> Self

👎Deprecated since 0.41.0: This constructor is considered ambiguous regarding the executor. Use one of the new, executor-specific constructors or Swarm::with_threadpool_executor for the same behaviour.

Builds a new Swarm.

pub fn with_executor(
    transport: Boxed<(PeerId, StreamMuxerBox)>,
    behaviour: TBehaviour,
    local_peer_id: PeerId,
    executor: impl Executor + Send + 'static
) -> Self

Builds a new Swarm with a provided executor.

pub fn with_tokio_executor(
    transport: Boxed<(PeerId, StreamMuxerBox)>,
    behaviour: TBehaviour,
    local_peer_id: PeerId
) -> Self

Available on crate feature tokio and neither Emscripten nor WASI nor target_os="unknown" only.

Builds a new Swarm with a tokio executor.

pub fn with_async_std_executor(
    transport: Boxed<(PeerId, StreamMuxerBox)>,
    behaviour: TBehaviour,
    local_peer_id: PeerId
) -> Self

Available on crate feature async-std and neither Emscripten nor WASI nor target_os="unknown" only.

Builds a new Swarm with an async-std executor.

pub fn with_threadpool_executor(
    transport: Boxed<(PeerId, StreamMuxerBox)>,
    behaviour: TBehaviour,
    local_peer_id: PeerId
) -> Self

Builds a new Swarm with a threadpool executor.

pub fn with_wasm_executor(
    transport: Boxed<(PeerId, StreamMuxerBox)>,
    behaviour: TBehaviour,
    local_peer_id: PeerId
) -> Self

Available on crate feature wasm-bindgen only.

Builds a new Swarm with a wasm executor. Background tasks will be executed by the browser on the next micro-tick.

Spawning a task is similar too:

function spawn(task: () => Promise<void>) {
    task()
}

pub fn without_executor(
    transport: Boxed<(PeerId, StreamMuxerBox)>,
    behaviour: TBehaviour,
    local_peer_id: PeerId
) -> Self

Builds a new Swarm without an executor, instead using the current task.

⚠️ Performance warning

All connections will be polled on the current task, thus quite bad performance characteristics should be expected. Whenever possible use an executor and Swarm::with_executor.

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 = Swarm::new(
  DummyTransport::new().boxed(),
  dummy::Behaviour,
  PeerId::random(),
);

// 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 = &AddressRecord>

Returns an iterator for AddressRecords of external addresses of the local node, in decreasing order of their current score.

pub fn add_external_address(
    &mut self,
    a: Multiaddr,
    s: AddressScore
) -> AddAddressResult

Adds an external address record for the local node.

An external address is an address of the local node known to be (likely) reachable for other nodes, possibly taking into account NAT. The external addresses of the local node may be shared with other nodes by the NetworkBehaviour.

The associated score determines both the position of the address in the list of external addresses (which can determine the order in which addresses are used to connect to) as well as how long the address is retained in the list, depending on how frequently it is reported by the NetworkBehaviour via NetworkBehaviourAction::ReportObservedAddr or explicitly through this method.

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

Removes an external address of the local node, regardless of its current score. See Swarm::add_external_address for details.

Returns true if the address existed and was removed, false otherwise.

pub fn ban_peer_id(&mut self, peer_id: PeerId)

Bans a peer by its peer ID.

Any incoming connection and any dialing attempt will immediately be rejected. This function has no effect if the peer is already banned.

pub fn unban_peer_id(&mut self, peer_id: PeerId)

Unbans a peer.

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.

Note: Closing a connection via Swarm::disconnect_peer_id does not inform the corresponding ConnectionHandler. Closing a connection via a ConnectionHandler can be done either in a collaborative manner across ConnectionHandlers with ConnectionHandler::connection_keep_alive or directly with ConnectionHandlerEvent::Close.

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 [Stream::poll_next] will never return Poll::Ready(None).

type Item = SwarmEvent<<TBehaviour as NetworkBehaviour>::OutEvent, <<<TBehaviour as NetworkBehaviour>::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::Error>

Values yielded by the stream.

fn poll_next(
    self: Pin<&mut Self>,
    cx: &mut Context<'_>
) -> Poll<Option<Self::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,