Struct tokio::net::TcpSocket

pub struct TcpSocket { /* fields omitted */ }

A TCP socket that has not yet been converted to a TcpStream or TcpListener.

TcpSocket wraps an operating system socket and enables the caller to configure the socket before establishing a TCP connection or accepting inbound connections. The caller is able to set socket option and explicitly bind the socket with a socket address.

The underlying socket is closed when the TcpSocket value is dropped.

TcpSocket should only be used directly if the default configuration used by TcpStream::connect and TcpListener::bind does not meet the required use case.

Calling TcpStream::connect("127.0.0.1:8080") is equivalent to:

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    let stream = socket.connect(addr).await?;

    Ok(())
}

Calling TcpListener::bind("127.0.0.1:8080") is equivalent to:

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    // On platforms with Berkeley-derived sockets, this allows to quickly
    // rebind a socket, without needing to wait for the OS to clean up the
    // previous one.
    //
    // On Windows, this allows rebinding sockets which are actively in use,
    // which allows “socket hijacking”, so we explicitly don't set it here.
    // https://docs.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse
    socket.set_reuseaddr(true)?;
    socket.bind(addr)?;

    let listener = socket.listen(1024)?;

    Ok(())
}

Setting socket options not explicitly provided by TcpSocket may be done by accessing the RawFd/RawSocket using AsRawFd/AsRawSocket and setting the option with a crate like socket2.

Implementations

impl TcpSocket

pub fn new_v4() -> Result<TcpSocket>

Create a new socket configured for IPv4.

Calls socket(2) with AF_INET and SOCK_STREAM.

Returns

On success, the newly created TcpSocket is returned. If an error is encountered, it is returned instead.

Examples

Create a new IPv4 socket and start listening.

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();
    let socket = TcpSocket::new_v4()?;
    socket.bind(addr)?;

    let listener = socket.listen(128)?;
    Ok(())
}

pub fn new_v6() -> Result<TcpSocket>

Create a new socket configured for IPv6.

Calls socket(2) with AF_INET6 and SOCK_STREAM.

Returns

On success, the newly created TcpSocket is returned. If an error is encountered, it is returned instead.

Examples

Create a new IPv6 socket and start listening.

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "[::1]:8080".parse().unwrap();
    let socket = TcpSocket::new_v6()?;
    socket.bind(addr)?;

    let listener = socket.listen(128)?;
    Ok(())
}

pub fn set_reuseaddr(&self, reuseaddr: bool) -> Result<()>

Allow the socket to bind to an in-use address.

Behavior is platform specific. Refer to the target platform's documentation for more details.

Examples

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    socket.set_reuseaddr(true)?;
    socket.bind(addr)?;

    let listener = socket.listen(1024)?;

    Ok(())
}

pub fn reuseaddr(&self) -> Result<bool>

Retrieves the value set for SO_REUSEADDR on this socket

Examples

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    socket.set_reuseaddr(true)?;
    assert!(socket.reuseaddr().unwrap());
    socket.bind(addr)?;

    let listener = socket.listen(1024)?;
    Ok(())
}

pub fn set_reuseport(&self, reuseport: bool) -> Result<()>

Allow the socket to bind to an in-use port. Only available for unix systems (excluding Solaris & Illumos).

Behavior is platform specific. Refer to the target platform's documentation for more details.

Examples

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    socket.set_reuseport(true)?;
    socket.bind(addr)?;

    let listener = socket.listen(1024)?;
    Ok(())
}

pub fn reuseport(&self) -> Result<bool>

Allow the socket to bind to an in-use port. Only available for unix systems (excluding Solaris & Illumos).

Behavior is platform specific. Refer to the target platform's documentation for more details.

Examples

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    socket.set_reuseport(true)?;
    assert!(socket.reuseport().unwrap());
    socket.bind(addr)?;

    let listener = socket.listen(1024)?;
    Ok(())
}

pub fn local_addr(&self) -> Result<SocketAddr>

Get the local address of this socket.

Will fail on windows if called before bind.

Examples

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    socket.bind(addr)?;
    assert_eq!(socket.local_addr().unwrap().to_string(), "127.0.0.1:8080");
    let listener = socket.listen(1024)?;
    Ok(())
}

pub fn bind(&self, addr: SocketAddr) -> Result<()>

Bind the socket to the given address.

This calls the bind(2) operating-system function. Behavior is platform specific. Refer to the target platform's documentation for more details.

Examples

Bind a socket before listening.

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    socket.bind(addr)?;

    let listener = socket.listen(1024)?;

    Ok(())
}

pub async fn connect(self, addr: SocketAddr) -> Result<TcpStream>

Establish a TCP connection with a peer at the specified socket address.

The TcpSocket is consumed. Once the connection is established, a connected TcpStream is returned. If the connection fails, the encountered error is returned.

This calls the connect(2) operating-system function. Behavior is platform specific. Refer to the target platform's documentation for more details.

Examples

Connecting to a peer.

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    let stream = socket.connect(addr).await?;

    Ok(())
}

pub fn listen(self, backlog: u32) -> Result<TcpListener>

Convert the socket into a TcpListener.

backlog defines the maximum number of pending connections are queued by the operating system at any given time. Connection are removed from the queue with TcpListener::accept. When the queue is full, the operationg-system will start rejecting connections.

This calls the listen(2) operating-system function, marking the socket as a passive socket. Behavior is platform specific. Refer to the target platform's documentation for more details.

Examples

Create a TcpListener.

use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    socket.bind(addr)?;

    let listener = socket.listen(1024)?;

    Ok(())
}

Trait Implementations

impl AsRawFd for TcpSocket

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for TcpSocket

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromRawFd for TcpSocket

unsafe fn from_raw_fd(fd: RawFd) -> TcpSocket

Converts a RawFd to a TcpSocket.

Notes

The caller is responsible for ensuring that the socket is in non-blocking mode.