Struct libp2p::core::nodes::listeners::ListenersStream

pub struct ListenersStream<TTrans> where
    TTrans: Transport,  { /* fields omitted */ }

Implementation of futures::Stream that allows listening on multiaddresses.

To start using a ListenersStream, create one with new by passing an implementation of Transport. This Transport will be used to start listening, therefore you want to pass a Transport that supports the protocols you wish you listen on.

Then, call ListenerStream::listen_on for all addresses you want to start listening on.

The ListenersStream never ends and never produces errors. If a listener errors or closes, an event is generated on the stream and the listener is then dropped, but the ListenersStream itself continues.

Example

use futures::prelude::*;
use libp2p_core::nodes::listeners::{ListenersEvent, ListenersStream};

let mut listeners = ListenersStream::new(libp2p_tcp::TcpConfig::new());

// Ask the `listeners` to start listening on the given multiaddress.
listeners.listen_on("/ip4/0.0.0.0/tcp/0".parse().unwrap()).unwrap();

// The `listeners` will now generate events when polled.
futures::executor::block_on(async move {
    while let Some(event) = listeners.next().await {
        match event {
            ListenersEvent::NewAddress { listener_id, listen_addr } => {
                println!("Listener {:?} is listening at address {}", listener_id, listen_addr);
            },
            ListenersEvent::AddressExpired { listener_id, listen_addr } => {
                println!("Listener {:?} is no longer listening at address {}", listener_id, listen_addr);
            },
            ListenersEvent::Closed { listener_id, .. } => {
                println!("Listener {:?} has been closed", listener_id);
            },
            ListenersEvent::Error { listener_id, error } => {
                println!("Listener {:?} has experienced an error: {}", listener_id, error);
            },
            ListenersEvent::Incoming { listener_id, upgrade, local_addr, .. } => {
                println!("Listener {:?} has a new connection on {}", listener_id, local_addr);
                // We don't do anything with the newly-opened connection, but in a real-life
                // program you probably want to use it!
                drop(upgrade);
            },
        }
    }
})

Methods

impl<TTrans> ListenersStream<TTrans> where
    TTrans: Transport, 

pub fn new(transport: TTrans) -> ListenersStream<TTrans>

Starts a new stream of listeners.

pub fn with_capacity(
    transport: TTrans,
    capacity: usize
) -> ListenersStream<TTrans>

Same as new, but pre-allocates enough memory for the given number of simultaneous listeners.

pub fn listen_on(
    &mut self,
    addr: Multiaddr
) -> Result<ListenerId, TransportError<<TTrans as Transport>::Error>> where
    TTrans: Clone, 

Start listening on a multiaddress.

Returns an error if the transport doesn't support the given multiaddress.

pub fn remove_listener(&mut self, id: ListenerId) -> Result<(), ()>

Remove the listener matching the given ListenerId.

Return Ok(()) if a listener with this ID was in the list.

pub fn transport(&self) -> &TTrans

Returns the transport passed when building this object.

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

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

pub fn poll(
    self: Pin<&mut ListenersStream<TTrans>>,
    cx: &mut Context
) -> Poll<ListenersEvent<TTrans>>

Provides an API similar to Stream, except that it cannot end.

Trait Implementations

impl<TTrans> Debug for ListenersStream<TTrans> where
    TTrans: Transport + Debug, 

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl<TTrans> Stream for ListenersStream<TTrans> where
    TTrans: Transport, 

type Item = ListenersEvent<TTrans>

Values yielded by the stream.

fn poll_next(
    self: Pin<&mut ListenersStream<TTrans>>,
    cx: &mut Context
) -> Poll<Option<<ListenersStream<TTrans> 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<TTrans> Unpin for ListenersStream<TTrans> where
    TTrans: Transport,