Struct tokio::net::TcpListener [−][src]
A TCP socket server, listening for connections.
You can accept a new connection by using the accept
method. Alternatively TcpListener
implements the Stream
trait, which allows you to use the listener in places that want a
stream. The stream will never return None
and will also not yield the peer’s SocketAddr
structure. Iterating over
it is equivalent to calling accept in a loop.
Errors
Note that accepting a connection can lead to various errors and not all of them are necessarily fatal ‒ for example having too many open file descriptors or the other side closing the connection while it waits in an accept queue. These would terminate the stream if not handled in any way.
Examples
Using accept
:
use tokio::net::TcpListener; use std::io; async fn process_socket<T>(socket: T) { // do work with socket here } #[tokio::main] async fn main() -> io::Result<()> { let mut listener = TcpListener::bind("127.0.0.1:8080").await?; loop { let (socket, _) = listener.accept().await?; process_socket(socket).await; } }
Using impl Stream
:
use tokio::{net::TcpListener, stream::StreamExt}; #[tokio::main] async fn main() { let mut listener = TcpListener::bind("127.0.0.1:8080").await.unwrap(); while let Some(stream) = listener.next().await { match stream { Ok(stream) => { println!("new client!"); } Err(e) => { /* connection failed */ } } } }
Implementations
impl TcpListener
[src]
pub async fn bind<A: ToSocketAddrs>(addr: A) -> Result<TcpListener>
[src]
Creates a new TcpListener, which will be bound to the specified address.
The returned listener is ready for accepting connections.
Binding with a port number of 0 will request that the OS assigns a port
to this listener. The port allocated can be queried via the local_addr
method.
The address type can be any implementor of the ToSocketAddrs
trait.
Note that strings only implement this trait when the dns
feature
is enabled, as strings may contain domain names that need to be resolved.
If addr
yields multiple addresses, bind will be attempted with each of
the addresses until one succeeds and returns the listener. If none of
the addresses succeed in creating a listener, the error returned from
the last attempt (the last address) is returned.
This function sets the SO_REUSEADDR
option on the socket.
Examples
use tokio::net::TcpListener; use std::io; #[tokio::main] async fn main() -> io::Result<()> { let listener = TcpListener::bind("127.0.0.1:2345").await?; // use the listener Ok(()) }
Without the dns
feature:
use tokio::net::TcpListener; use std::net::Ipv4Addr; use std::io; #[tokio::main] async fn main() -> io::Result<()> { let listener = TcpListener::bind((Ipv4Addr::new(127, 0, 0, 1), 2345)).await?; // use the listener Ok(()) }
pub async fn accept(&mut self) -> Result<(TcpStream, SocketAddr)>
[src]
Accepts a new incoming connection from this listener.
This function will yield once a new TCP connection is established. When
established, the corresponding TcpStream
and the remote peer’s
address will be returned.
Examples
use tokio::net::TcpListener; use std::io; #[tokio::main] async fn main() -> io::Result<()> { let mut listener = TcpListener::bind("127.0.0.1:8080").await?; match listener.accept().await { Ok((_socket, addr)) => println!("new client: {:?}", addr), Err(e) => println!("couldn't get client: {:?}", e), } Ok(()) }
pub fn poll_accept(
&mut self,
cx: &mut Context<'_>
) -> Poll<Result<(TcpStream, SocketAddr)>>
[src]
&mut self,
cx: &mut Context<'_>
) -> Poll<Result<(TcpStream, SocketAddr)>>
Polls to accept a new incoming connection to this listener.
If there is no connection to accept, Poll::Pending
is returned and
the current task will be notified by a waker.
pub fn from_std(listener: TcpListener) -> Result<TcpListener>
[src]
Creates a new TCP listener from the standard library’s TCP listener.
This method can be used when the Handle::tcp_listen
method isn’t
sufficient because perhaps some more configuration is needed in terms of
before the calls to bind
and listen
.
This API is typically paired with the net2
crate and the TcpBuilder
type to build up and customize a listener before it’s shipped off to the
backing event loop. This allows configuration of options like
SO_REUSEPORT
, binding to multiple addresses, etc.
The addr
argument here is one of the addresses that listener
is
bound to and the listener will only be guaranteed to accept connections
of the same address type currently.
The platform specific behavior of this function looks like:
-
On Unix, the socket is placed into nonblocking mode and connections can be accepted as normal
-
On Windows, the address is stored internally and all future accepts will only be for the same IP version as
addr
specified. That is, ifaddr
is an IPv4 address then all sockets accepted will be IPv4 as well (same for IPv6).
Examples
use std::error::Error; use tokio::net::TcpListener; #[tokio::main] async fn main() -> Result<(), Box<dyn Error>> { let std_listener = std::net::TcpListener::bind("127.0.0.1:0")?; let listener = TcpListener::from_std(std_listener)?; Ok(()) }
Panics
This function panics if thread-local runtime is not set.
The runtime is usually set implicitly when this function is called
from a future driven by a tokio runtime, otherwise runtime can be set
explicitly with Handle::enter
function.
pub fn local_addr(&self) -> Result<SocketAddr>
[src]
Returns the local address that this listener is bound to.
This can be useful, for example, when binding to port 0 to figure out which port was actually bound.
Examples
use tokio::net::TcpListener; use std::io; use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4}; #[tokio::main] async fn main() -> io::Result<()> { let listener = TcpListener::bind("127.0.0.1:8080").await?; assert_eq!(listener.local_addr()?, SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080))); Ok(()) }
pub fn incoming(&mut self) -> Incoming<'_>
[src]
Returns a stream over the connections being received on this listener.
Note that TcpListener
also directly implements Stream
.
The returned stream will never return None
and will also not yield the
peer’s SocketAddr
structure. Iterating over it is equivalent to
calling accept in a loop.
Errors
Note that accepting a connection can lead to various errors and not all of them are necessarily fatal ‒ for example having too many open file descriptors or the other side closing the connection while it waits in an accept queue. These would terminate the stream if not handled in any way.
Examples
use tokio::{net::TcpListener, stream::StreamExt}; #[tokio::main] async fn main() { let mut listener = TcpListener::bind("127.0.0.1:8080").await.unwrap(); let mut incoming = listener.incoming(); while let Some(stream) = incoming.next().await { match stream { Ok(stream) => { println!("new client!"); } Err(e) => { /* connection failed */ } } } }
pub fn ttl(&self) -> Result<u32>
[src]
Gets the value of the IP_TTL
option for this socket.
For more information about this option, see set_ttl
.
Examples
use tokio::net::TcpListener; use std::io; #[tokio::main] async fn main() -> io::Result<()> { let listener = TcpListener::bind("127.0.0.1:0").await?; listener.set_ttl(100).expect("could not set TTL"); assert_eq!(listener.ttl()?, 100); Ok(()) }
pub fn set_ttl(&self, ttl: u32) -> Result<()>
[src]
Sets the value for the IP_TTL
option on this socket.
This value sets the time-to-live field that is used in every packet sent from this socket.
Examples
use tokio::net::TcpListener; use std::io; #[tokio::main] async fn main() -> io::Result<()> { let listener = TcpListener::bind("127.0.0.1:0").await?; listener.set_ttl(100).expect("could not set TTL"); Ok(()) }
Trait Implementations
impl AsRawFd for TcpListener
[src]
impl Debug for TcpListener
[src]
impl Stream for TcpListener
[src]
type Item = Result<TcpStream>
Values yielded by the stream.
fn poll_next(
self: Pin<&mut Self>,
cx: &mut Context<'_>
) -> Poll<Option<Self::Item>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>
) -> Poll<Option<Self::Item>>
pub fn size_hint(&self) -> (usize, Option<usize>)
[src]
impl TryFrom<TcpListener> for TcpListener
[src]
type Error = Error
The type returned in the event of a conversion error.
fn try_from(stream: TcpListener) -> Result<Self, Self::Error>
[src]
Consumes stream, returning the tokio I/O object.
This is equivalent to
TcpListener::from_std(stream)
.
Auto Trait Implementations
impl !RefUnwindSafe for TcpListener
impl Send for TcpListener
impl Sync for TcpListener
impl Unpin for TcpListener
impl !UnwindSafe for TcpListener
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut Tⓘ
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<St> StreamExt for St where
St: Stream + ?Sized,
[src]
St: Stream + ?Sized,
fn next(&mut self) -> Next<'_, Self> where
Self: Unpin,
[src]
Self: Unpin,
fn try_next<T, E>(&mut self) -> TryNext<'_, Self> where
Self: Stream<Item = Result<T, E>> + Unpin,
[src]
Self: Stream<Item = Result<T, E>> + Unpin,
fn map<T, F>(self, f: F) -> Map<Self, F> where
F: FnMut(Self::Item) -> T,
Self: Sized,
[src]
F: FnMut(Self::Item) -> T,
Self: Sized,
fn merge<U>(self, other: U) -> Merge<Self, U> where
U: Stream<Item = Self::Item>,
Self: Sized,
[src]
U: Stream<Item = Self::Item>,
Self: Sized,
fn filter<F>(self, f: F) -> Filter<Self, F> where
F: FnMut(&Self::Item) -> bool,
Self: Sized,
[src]
F: FnMut(&Self::Item) -> bool,
Self: Sized,
fn filter_map<T, F>(self, f: F) -> FilterMap<Self, F> where
F: FnMut(Self::Item) -> Option<T>,
Self: Sized,
[src]
F: FnMut(Self::Item) -> Option<T>,
Self: Sized,
fn fuse(self) -> Fuse<Self> where
Self: Sized,
[src]
Self: Sized,
fn take(self, n: usize) -> Take<Self> where
Self: Sized,
[src]
Self: Sized,
fn take_while<F>(self, f: F) -> TakeWhile<Self, F> where
F: FnMut(&Self::Item) -> bool,
Self: Sized,
[src]
F: FnMut(&Self::Item) -> bool,
Self: Sized,
fn skip(self, n: usize) -> Skip<Self> where
Self: Sized,
[src]
Self: Sized,
fn skip_while<F>(self, f: F) -> SkipWhile<Self, F> where
F: FnMut(&Self::Item) -> bool,
Self: Sized,
[src]
F: FnMut(&Self::Item) -> bool,
Self: Sized,
fn all<F>(&mut self, f: F) -> AllFuture<'_, Self, F> where
Self: Unpin,
F: FnMut(Self::Item) -> bool,
[src]
Self: Unpin,
F: FnMut(Self::Item) -> bool,
fn any<F>(&mut self, f: F) -> AnyFuture<'_, Self, F> where
Self: Unpin,
F: FnMut(Self::Item) -> bool,
[src]
Self: Unpin,
F: FnMut(Self::Item) -> bool,
fn chain<U>(self, other: U) -> Chain<Self, U> where
U: Stream<Item = Self::Item>,
Self: Sized,
[src]
U: Stream<Item = Self::Item>,
Self: Sized,
fn fold<B, F>(self, init: B, f: F) -> FoldFuture<Self, B, F> where
Self: Sized,
F: FnMut(B, Self::Item) -> B,
[src]
Self: Sized,
F: FnMut(B, Self::Item) -> B,
fn collect<T>(self) -> Collect<Self, T> where
T: FromStream<Self::Item>,
Self: Sized,
[src]
T: FromStream<Self::Item>,
Self: Sized,
fn timeout(self, duration: Duration) -> Timeout<Self> where
Self: Sized,
[src]
Self: Sized,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<S, T, E> TryStream for S where
S: Stream<Item = Result<T, E>> + ?Sized,
[src]
S: Stream<Item = Result<T, E>> + ?Sized,