Struct std::net::TcpListener

1.0.0 · source ·

pub struct TcpListener(_);

Expand description

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(())
}

Run

Implementations§

source §

impl TcpListener

source

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();

Run

创建绑定到 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();

Run

创建绑定到操作系统在 127.0.0.1 分配的端口的 TCP 侦听器。

use std::net::TcpListener;

let socket = TcpListener::bind("127.0.0.1:0").unwrap();

Run

source

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)));

Run

source

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();

Run

source

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:?}"),
}

Run

source

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")?;

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

Run

source

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", port)).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(())
}

Run

1.9.0 · source

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");

Run

1.9.0 · source

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);

Run

1.9.0 · source

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

1.9.0 · source

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

👎Deprecated since 1.16.0: this option can only be set before the socket is bound

1.9.0 · source

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");

Run

1.9.0 · source

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}"),
    }
}