# [−] [src] Struct tokio::net::TcpListener

    pub struct TcpListener { /* fields omitted */ }

A TCP socket server, listening for connections.

You can accept a new connection by using the `accept` method.

# 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

### `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 `net` 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(())
    }

#### `pub async fn accept<'_>(&'_ 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 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(
&self,
cx: &mut Context<'_>
) -> Poll<Result<(TcpStream, SocketAddr)>>` [src]

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.

#### `pub fn from_std(listener: TcpListener) -> Result<TcpListener>` [src]

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.

#### `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 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]

#### `fn as_raw_fd(&self) -> RawFd` [src]

Extracts the raw file descriptor. Read more

### `impl Debug for TcpListener` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `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]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `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]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `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]

Performs the conversion.