Ch26.14: Networking

中文(简体)

1. Sockets Are Devices

fast_io does not have a separate socket stream hierarchy. A socket is a device, and the same print, scan, read, write and transmit operations apply. The networking layer only creates the handle and translates addresses.

Type Role Module
native_socket_file Owning native socket handle; unbuffered. fast_io
iobuf_socket_file Buffered socket; the normal type for formatted TCP I/O. fast_io
native_dns_file Owning DNS result set for a host name. fast_io
ip, ipv4, ipv6 Address and port value types. fast_io
net_service RAII network subsystem guard (WSA on Windows; SIGPIPE policy on POSIX). header-side

On POSIX, a socket is a file descriptor, so native_socket_file is the same type as native_file and iobuf_socket_file is the same type as iobuf_file. On Windows, sockets are separate handles, so the socket types are distinct.

2. TCP Helpers

Entry Signature Meaning
tcp_connect tcp_connect(ip, open_mode = {}) Create a connected TCP socket.
tcp_connect tcp_connect(ipv4, open_mode = {}), tcp_connect(ipv6, open_mode = {}) Address-family-specific forms.
tcp_listen tcp_listen(std::uint_least16_t port, open_mode = {}) Dual-stack listener on a port.
tcp_listen tcp_listen(ipv4, open_mode = {}), tcp_listen(ipv6, open_mode = {}) Bind a listener to a specific address.

auto listener{::fast_io::tcp_listen(8080u16)};
::fast_io::native_socket_file conn{::fast_io::posix_accept(listener)};
::fast_io::iobuf_socket_file buf_conn{::fast_io::io::transmit(conn)};

tcp_listen keeps the socket in listening mode; tcp_connect returns a factory that becomes an owning socket file. open_mode::no_block selects a non-blocking socket for the async layer.

3. DNS

native_dns_file owns the resolver result. Iterate it for every address, or call to_ip(dns, port) for the first result with a port attached.


::fast_io::native_dns_file dns{u8"example.com"};
::fast_io::iobuf_socket_file sock{
    ::fast_io::tcp_connect(::fast_io::to_ip(dns, 80u16))};
Entry Meaning
native_dns_file(host) Resolve a UTF-8 host name.
to_ip(dns, port) First resolved address with the given port.
to_ip_address(dns) First resolved address without a port.
begin(dns) / end(dns) Iterate all resolver entries.

The resolver does not retry forever and does not pick a “best” address behind your back. Iterate the result set when the host has both IPv4 and IPv6 records.

4. Socket Free Functions

The lower-level operations mirror the POSIX names and work on socket observers:

Operation Meaning
posix_connect(sock, addr, len)Connect to a peer.
posix_bind(sock, addr, len)Bind a local address.
posix_listen(sock, backlog)Put a bound socket into listening mode.
posix_accept(listener)Accept one connection.
posix_recvfrom, posix_sendtoDatagram send/receive.
posix_setsockopt, posix_getpeernameSocket options and peer address.

These are header-side. The TCP helpers above are the portable path; the free functions are for protocol work that needs the raw address or option.

5. net_service

On Windows, the networking subsystem must be initialized before any socket operation. net_service performs WSAStartup in its constructor and WSACleanup in its destructor. On POSIX it is a no-op object, kept for portability exercises.

On POSIX, net_service also controls the SIGPIPE policy. By default it ignores SIGPIPE so a write to a closed peer returns an error instead of terminating the process. The posix_no_ignore_sigpipe flag preserves the default disposition.


::fast_io::net_service net_svc;

Create one at the start of main and keep it alive for the program's network lifetime. Do not create it inside a short-lived worker scope.

6. Protocol Support

The socket API is a thin wrapper over the OS socket interface. The supported protocol list is the OS list, not a fast_io list:

TCP and UDP have convenience helpers. Other families are constructed from native socket handles and the raw address structures.

7. Module and Header Boundary

The fast_io module exports native_socket_file, iobuf_socket_file, native_dns_file, to_ip, to_ip_address, ip, ipv4, ipv6 and the address types. net_service, tcp_connect, tcp_listen and the raw posix_* socket free functions are header-side today.

Do not mix socket and file owners. An accepted socket is a native handle. Wrapping it in native_socket_file transfers ownership; wrapping the same handle again will double-close it.

Key Takeaways