Struct std::net::TcpListener

pub struct TcpListener(_);

TCP 套接字服务器，侦听连接。

通过将 TcpListener 绑定到套接字地址来创建 TcpListener 之后，它会侦听传入的 TCP 连接。 可以通过调用 accept 或在 incoming 返回的 Incoming 迭代器上进行迭代来接受它们。

丢弃该值时，套接字将关闭。

传输控制协议在 IETF RFC 793 中指定。

Examples

use std::net::{TcpListener, TcpStream};

fn handle_client(stream: TcpStream) {
    // ...
}

fn main() -> std::io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:80")?;

    // 接受连接并顺序处理它们
    for stream in listener.incoming() {
        handle_client(stream?);
    }
    Ok(())
}

Implementations

impl TcpListener

pub fn bind<A: ToSocketAddrs>(addr: A) -> Result<TcpListener>

创建一个新的 TcpListener，它将绑定到指定的地址。

返回的侦听器已准备好接受连接。

端口号为 0 的绑定将要求 OS 为该侦听器分配端口。 可以通过 TcpListener::local_addr 方法查询分配的端口。

地址类型可以是 ToSocketAddrs trait 的任何实现者。有关具体的例子，请参见其文档。

如果 addr 产生多个地址，则将对每个地址尝试 bind，直到一个成功并返回侦听器为止。

如果没有一个地址成功创建侦听器，则返回从上次尝试 (最后一个地址) 返回的错误。

Examples

创建绑定到 127.0.0.1:80 的 TCP 侦听器：

use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();

创建绑定到 127.0.0.1:80 的 TCP 侦听器。如果失败，请创建绑定到 127.0.0.1:443 的 TCP 侦听器：

use std::net::{SocketAddr, TcpListener};

let addrs = [
    SocketAddr::from(([127, 0, 0, 1], 80)),
    SocketAddr::from(([127, 0, 0, 1], 443)),
];
let listener = TcpListener::bind(&addrs[..]).unwrap();

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

返回此侦听器的本地套接字地址。

Examples

use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpListener};

let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
assert_eq!(listener.local_addr().unwrap(),
           SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));

pub fn try_clone(&self) -> Result<TcpListener>

为底层套接字创建一个新的独立的拥有所有权的句柄。

返回的 TcpListener 是与此对象引用相同的套接字的引用。 这两个句柄均可用于接受传入连接，并且在一个侦听器上设置的选项将影响另一个。

Examples

use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
let listener_clone = listener.try_clone().unwrap();

pub fn accept(&self) -> Result<(TcpStream, SocketAddr)>

接受来自此侦听器的新传入连接。

该函数将阻塞调用线程，直到建立新的 TCP 连接为止。 建立后，将返回相应的 TcpStream 和远程对等方的地址。

Examples

use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
match listener.accept() {
    Ok((_socket, addr)) => println!("new client: {:?}", addr),
    Err(e) => println!("couldn't get client: {:?}", e),
}

pub fn incoming(&self) -> Incoming<'_>

返回在此侦听器上接收到的连接上的迭代器。

返回的迭代器将永远不会返回 None，也不会产生对等方的 SocketAddr 结构体。 对其进行迭代等效于在循环中调用 TcpListener::accept。

Examples

use std::net::{TcpListener, TcpStream};

fn handle_connection(stream: TcpStream) {
   // ...
}

fn main() -> std::io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:80").unwrap();

    for stream in listener.incoming() {
        match stream {
            Ok(stream) => {
                handle_connection(stream);
            }
            Err(e) => { /* connection failed */ }
        }
    }
    Ok(())
}

pub fn into_incoming(self) -> IntoIncoming

🔬 This is a nightly-only experimental API. (tcplistener_into_incoming #88339)

在此侦听器上接收到的连接上将其转换为迭代器。

返回的迭代器将永远不会返回 None，也不会产生对等方的 SocketAddr 结构体。 对其进行迭代等效于在循环中调用 TcpListener::accept。

Examples

#![feature(tcplistener_into_incoming)]
use std::net::{TcpListener, TcpStream};

fn listen_on(port: u16) -> impl Iterator<Item = TcpStream> {
    let listener = TcpListener::bind("127.0.0.1:80").unwrap();
    listener.into_incoming()
        .filter_map(Result::ok) /* Ignore failed connections */
}

fn main() -> std::io::Result<()> {
    for stream in listen_on(80) {
        /* handle the connection here */
    }
    Ok(())
}

pub fn set_ttl(&self, ttl: u32) -> Result<()>

设置此套接字上 IP_TTL 选项的值。

此值设置从该套接字发送的每个数据包中使用的生存时间字段。

Examples

use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();
listener.set_ttl(100).expect("could not set TTL");

pub fn ttl(&self) -> Result<u32>

获取此套接字的 IP_TTL 选项的值。

有关此选项的更多信息，请参见 TcpListener::set_ttl。

Examples

use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();
listener.set_ttl(100).expect("could not set TTL");
assert_eq!(listener.ttl().unwrap_or(0), 100);

pub fn set_only_v6(&self, only_v6: bool) -> Result<()>

👎 Deprecated since 1.16.0:

this option can only be set before the socket is bound

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

👎 Deprecated since 1.16.0:

this option can only be set before the socket is bound

pub fn take_error(&self) -> Result<Option<Error>>

获取此套接字上 SO_ERROR 选项的值。

这将检索底层套接字中存储的错误，从而清除进程中的字段。 这对于检查两次调用之间的错误很有用。

Examples

use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();
listener.take_error().expect("No error was expected");

pub fn set_nonblocking(&self, nonblocking: bool) -> Result<()>

将此 TCP 流移入或移出非阻塞模式。

这将导致 accept 操作变为非阻塞，即立即从其调用中返回。 如果 IO 操作成功，则返回 Ok，并且不需要进一步的操作。 如果 IO 操作无法完成，需要重试，则返回类型为 io::ErrorKind::WouldBlock 的错误。

在 Unix 平台上，调用此方法相当于调用 fcntl FIONBIO。 在 Windows 上，调用此方法对应于调用 ioctlsocket FIONBIO。

Examples

将 TCP 侦听器绑定到地址，侦听连接，并以非阻塞模式读取字节：

use std::io;
use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:7878").unwrap();
listener.set_nonblocking(true).expect("Cannot set non-blocking");

for stream in listener.incoming() {
    match stream {
        Ok(s) => {
            // 用 TcpStream 做某事
            handle_connection(s);
        }
        Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
            // 等待网络套接字就绪，通常通过平台特定的 API (例如 epoll 或 IOCP) 实现
            wait_for_fd();
            continue;
        }
        Err(e) => panic!("encountered IO error: {}", e),
    }
}

Trait Implementations

impl AsFd for TcpListener

fn as_fd(&self) -> BorrowedFd<'_>

🔬 This is a nightly-only experimental API. (io_safety #87074)

This is supported on Unix only.

借用文件描述符。

impl AsRawFd for TcpListener

fn as_raw_fd(&self) -> RawFd

This is supported on Unix only.

提取原始文件描述符。

impl AsRawSocket for TcpListener

This is supported on Windows only.

fn as_raw_socket(&self) -> RawSocket

从此对象中提取底层原始套接字。

impl AsSocket for TcpListener

This is supported on Windows only.

fn as_socket(&self) -> BorrowedSocket<'_>

🔬 This is a nightly-only experimental API. (io_safety #87074)

借用套接字。

impl Debug for TcpListener

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

使用给定的格式化程序格式化该值。

impl From<OwnedFd> for TcpListener

fn from(owned_fd: OwnedFd) -> Self

执行转换。

impl From<OwnedSocket> for TcpListener

This is supported on Windows only.

fn from(owned: OwnedSocket) -> Self

执行转换。

impl From<TcpListener> for OwnedSocket

This is supported on Windows only.

fn from(tcp_listener: TcpListener) -> OwnedSocket

执行转换。

impl From<TcpListener> for OwnedFd

fn from(tcp_listener: TcpListener) -> OwnedFd

执行转换。

impl FromRawFd for TcpListener

unsafe fn from_raw_fd(fd: RawFd) -> TcpListener

This is supported on Unix only.

根据给定的原始文件描述符构造 Self 的新实例。

impl FromRawSocket for TcpListener

This is supported on Windows only.

unsafe fn from_raw_socket(sock: RawSocket) -> TcpListener

从给定的原始套接字创建一个新的 I/O 对象。

impl IntoRawFd for TcpListener

fn into_raw_fd(self) -> RawFd

This is supported on Unix only.

消费这个对象，返回原始的底层文件描述符。

impl IntoRawSocket for TcpListener

This is supported on Windows only.

fn into_raw_socket(self) -> RawSocket

消耗此对象，返回原始底层套接字。