Trait Transport
pub trait Transport {
type Output;
type Error: Error;
type ListenerUpgrade: Future<Output = Result<Self::Output, Self::Error>>;
type Dial: Future<Output = Result<Self::Output, Self::Error>>;
// Required methods
fn listen_on(
&mut self,
id: ListenerId,
addr: Multiaddr,
) -> Result<(), TransportError<Self::Error>>;
fn remove_listener(&mut self, id: ListenerId) -> bool;
fn dial(
&mut self,
addr: Multiaddr,
opts: DialOpts,
) -> Result<Self::Dial, TransportError<Self::Error>>;
fn poll(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
) -> Poll<TransportEvent<Self::ListenerUpgrade, Self::Error>>;
// Provided methods
fn boxed(self) -> Boxed<Self::Output>
where Self: Sized + Send + Unpin + 'static,
Self::Dial: Send + 'static,
Self::ListenerUpgrade: Send + 'static,
Self::Error: Send + Sync { ... }
fn map<F, O>(self, f: F) -> Map<Self, F>
where Self: Sized,
F: FnOnce(Self::Output, ConnectedPoint) -> O { ... }
fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
where Self: Sized,
F: FnOnce(Self::Error) -> E { ... }
fn or_transport<U>(self, other: U) -> OrTransport<Self, U>
where Self: Sized,
U: Transport,
<U as Transport>::Error: 'static { ... }
fn and_then<C, F, O>(self, f: C) -> AndThen<Self, C>
where Self: Sized,
C: FnOnce(Self::Output, ConnectedPoint) -> F,
F: TryFuture<Ok = O>,
<F as TryFuture>::Error: Error + 'static { ... }
fn upgrade(self, version: Version) -> Builder<Self>
where Self: Sized,
Self::Error: 'static { ... }
}Expand description
A transport provides connection-oriented communication between two peers through ordered streams of data (i.e. connections).
Connections are established either by listening
or dialing on a Transport. A peer that
obtains a connection by listening is often referred to as the listener and the
peer that initiated the connection through dialing as the dialer, in
contrast to the traditional roles of server and client.
Most transports also provide a form of reliable delivery on the established connections but the precise semantics of these guarantees depend on the specific transport.
This trait is implemented for concrete connection-oriented transport protocols like TCP or Unix Domain Sockets, but also on wrappers that add additional functionality to the dialing or listening process (e.g. name resolution via the DNS).
Additional protocols can be layered on top of the connections established
by a Transport through an upgrade mechanism that is initiated via
upgrade.
Note for implementors: Futures returned by Transport::dial should only
do work once polled for the first time. E.g. in the case of TCP, connecting
to the remote should not happen immediately on Transport::dial but only
once the returned Future is polled. The caller of Transport::dial
may call the method multiple times with a set of addresses, racing a subset
of the returned dials to success concurrently.
Required Associated Types§
type Output
type Output
The result of a connection setup process, including protocol upgrades.
Typically the output contains at least a handle to a data stream (i.e. a connection or a substream multiplexer on top of a connection) that provides APIs for sending and receiving data through the connection.
type ListenerUpgrade: Future<Output = Result<Self::Output, Self::Error>>
type ListenerUpgrade: Future<Output = Result<Self::Output, Self::Error>>
A pending Output for an inbound connection,
obtained from the Transport stream.
After a connection has been accepted by the transport, it may need to go through
asynchronous post-processing (i.e. protocol upgrade negotiations). Such
post-processing should not block the Listener from producing the next
connection, hence further connection setup proceeds asynchronously.
Once a ListenerUpgrade future resolves it yields the Output
of the connection setup process.
Required Methods§
fn listen_on(
&mut self,
id: ListenerId,
addr: Multiaddr,
) -> Result<(), TransportError<Self::Error>>
fn listen_on( &mut self, id: ListenerId, addr: Multiaddr, ) -> Result<(), TransportError<Self::Error>>
Listens on the given Multiaddr for inbound connections with a provided ListenerId.
fn remove_listener(&mut self, id: ListenerId) -> bool
fn remove_listener(&mut self, id: ListenerId) -> bool
Remove a listener.
Return true if there was a listener with this Id, false
otherwise.
fn dial(
&mut self,
addr: Multiaddr,
opts: DialOpts,
) -> Result<Self::Dial, TransportError<Self::Error>>
fn dial( &mut self, addr: Multiaddr, opts: DialOpts, ) -> Result<Self::Dial, TransportError<Self::Error>>
Dials the given Multiaddr, returning a future for a pending outbound connection.
If TransportError::MultiaddrNotSupported is returned, it may be desirable to
try an alternative Transport, if available.
fn poll(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
) -> Poll<TransportEvent<Self::ListenerUpgrade, Self::Error>>
fn poll( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<TransportEvent<Self::ListenerUpgrade, Self::Error>>
Poll for TransportEvents.
A TransportEvent::Incoming should be produced whenever a connection is received at the lowest
level of the transport stack. The item must be a ListenerUpgrade
future that resolves to an Output value once all protocol upgrades have
been applied.
Transports are expected to produce TransportEvent::Incoming events only for
listen addresses which have previously been announced via
a TransportEvent::NewAddress event and which have not been invalidated by
an TransportEvent::AddressExpired event yet.
Provided Methods§
fn map<F, O>(self, f: F) -> Map<Self, F>
fn map<F, O>(self, f: F) -> Map<Self, F>
Applies a function on the connections created by the transport.
fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
Applies a function on the errors generated by the futures of the transport.
fn or_transport<U>(self, other: U) -> OrTransport<Self, U>
fn or_transport<U>(self, other: U) -> OrTransport<Self, U>
Adds a fallback transport that is used when encountering errors while establishing inbound or outbound connections.
The returned transport will act like self, except that if listen_on or dial
return an error then other will be tried.
fn and_then<C, F, O>(self, f: C) -> AndThen<Self, C>where
Self: Sized,
C: FnOnce(Self::Output, ConnectedPoint) -> F,
F: TryFuture<Ok = O>,
<F as TryFuture>::Error: Error + 'static,
fn and_then<C, F, O>(self, f: C) -> AndThen<Self, C>where
Self: Sized,
C: FnOnce(Self::Output, ConnectedPoint) -> F,
F: TryFuture<Ok = O>,
<F as TryFuture>::Error: Error + 'static,
Applies a function producing an asynchronous result to every connection created by this transport.
This function can be used for ad-hoc protocol upgrades or for processing or adapting the output for following configurations.
For the high-level transport upgrade procedure, see Transport::upgrade.