Struct tokio::net::TcpListener [−][src]
pub struct TcpListener { /* fields omitted */ }Expand description
A TCP socket server, listening for connections.
You can accept a new connection by using the accept
method.
A TcpListener can be turned into a Stream with TcpListenerStream.
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 listener = TcpListener::bind("127.0.0.1:8080").await?;
loop {
let (socket, _) = listener.accept().await?;
process_socket(socket).await;
}
}Implementations
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.
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.
To configure the socket before binding, you can use the TcpSocket
type.
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(())
}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.
Cancel safety
This method is cancel safe. If the method is used as the event in a
tokio::select! statement and some other branch
completes first, then it is guaranteed that no new connections were
accepted by this method.
Examples
use tokio::net::TcpListener;
use std::io;
#[tokio::main]
async fn main() -> io::Result<()> {
let 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(())
}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. Note that on multiple calls
to poll_accept, only the Waker from the Context passed to the most
recent call is scheduled to receive a wakeup.
Creates new TcpListener from a std::net::TcpListener.
This function is intended to be used to wrap a TCP listener from the standard library in the Tokio equivalent. The conversion assumes nothing about the underlying listener; it is left up to the user to set it in non-blocking mode.
This API is typically paired with the socket2 crate and the Socket
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.
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")?;
std_listener.set_nonblocking(true)?;
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 Runtime::enter function.
Turns a tokio::net::TcpListener into a std::net::TcpListener.
The returned std::net::TcpListener will have nonblocking mode set as
true. Use set_nonblocking to change the blocking mode if needed.
Examples
use std::error::Error;
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
let tokio_listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
let std_listener = tokio_listener.into_std()?;
std_listener.set_nonblocking(false)?;
Ok(())
}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(())
}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(())
}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
Consumes stream, returning the tokio I/O object.
This is equivalent to
TcpListener::from_std(stream).