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_sendto | Datagram send/receive. |
posix_setsockopt, posix_getpeername | Socket 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.
- Unix domain sockets on POSIX.
- Bluetooth sockets where the OS supports them.
- Raw sockets (usually requiring elevated privileges).
- Any other family exposed by the OS socket API.
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.
native_socket_file transfers ownership; wrapping the same
handle again will double-close it.
Key Takeaways
- A socket is a device;
print,scanandtransmitapply unchanged. native_socket_fileis unbuffered;iobuf_socket_fileis the formatted TCP type.tcp_connectandtcp_listenare the portable TCP helpers.native_dns_fileowns resolver results;to_ippicks one with a port.net_serviceis an RAII network guard and POSIX SIGPIPE policy object.- The protocol set is the OS socket set; raw sockets and some families need privileges.
net_service, TCP helpers and raw socket functions are header-side; the socket, DNS and address types are module-exported.