Reference

An io_context runs the event loop that completes I/O operations. A completed operation resumes the awaiting coroutine through that coroutine’s executor. Each I/O object belongs to one io_context. By default, an io_context uses IOCP on Windows, epoll on Linux, kqueue on BSD and macOS, and select on other POSIX systems. Each I/O backend has a tag type, such as epoll_t, and a tag value, such as epoll. Each tag type and tag value exists only on platforms where its I/O backend is available. The io_uring I/O backend, uring_t, needs Linux and liburing, and an io_context never uses it by default. Pass a tag value to the io_context constructor to choose the I/O backend at compile time. io_context_options holds the runtime tuning settings, including the locking_mode. See I/O Context and Configuration.

Sockets, acceptors, files, resolvers, signal sets, and the descriptor and handle types derive from io_object. io_stream combines io_read_stream and io_write_stream. A function that takes an io_stream reference accepts a TCP socket, a Unix domain stream socket, a stream file, or a stream descriptor or handle. shutdown_type selects which directions a socket’s shutdown closes. wait_type selects the readiness condition that completes the wait operation of a socket, an acceptor, or a posix_stream_descriptor. native_handle_type is the type of a platform descriptor or handle. See Sockets and Readiness Wait.

An endpoint pairs an IP address with a port. An ip_address holds either an ipv4_address or an ipv6_address. family names the address family of a socket or an address. The make_ functions in this section parse a string into an address or an endpoint. detect_endpoint_format reports which endpoint_format a string uses. See Endpoints.

A resolver resolves a host name and a service to a list of endpoints. It also resolves an endpoint back to an endpoint_name, which holds a host name and a service name. resolve_flags and reverse_flags change how each kind of query works. host_name returns the name of the local machine. See Name Resolution and DNS Lookup Tutorial.

A tcp_socket connects to a peer, then reads and writes a byte stream. A tcp_acceptor listens on an endpoint and accepts inbound connections. connect tries each endpoint in a range, in order, until one connects. The range is often the list of endpoints that a resolver returns. tcp_server manages a pool of reusable workers that handle accepted connections. See Sockets, Acceptors, and TCP Server.

A udp_socket sends and receives datagrams. In connectionless mode, each send names its destination, and each receive reports its sender. In connected mode, connect sets a default peer that send and receive use. message_flags modifies a single send or receive on a UDP socket or a Unix domain datagram socket. See UDP Sockets.

A Unix domain socket connects processes on the same machine through a filesystem path, which a local_endpoint holds. local_stream_socket and local_stream_acceptor work like their TCP counterparts. local_datagram_socket sends and receives datagrams, on POSIX systems only. connect_pair connects two sockets to each other, so the caller needs no path. bind_option controls whether an acceptor’s bind first removes an existing socket file at the path. See Unix Domain Sockets.

A socket option changes how the operating system handles a socket. Pass one to set_option or get_option on a socket or an acceptor. Each concrete option in socket_option supplies the platform’s protocol level and option name, so the calling code needs no platform headers. Most on-off options derive from socket_option::boolean_option, and the buffer-size options derive from socket_option::integer_option. The header <boost/corosio/native/native_socket_option.hpp> defines the same options inline, in namespace boost::corosio::native_socket_option, except any that the platform lacks, such as reuse_port without SO_REUSEPORT. That header includes the platform’s socket headers. See TCP_NODELAY and SO_REUSEADDR in the TCP/IP guide. See also the Socket Options and Multicast sections of the UDP guide.

co_await delay to suspend a coroutine for a duration or until a time point. A stop request on the coroutine’s stop token ends the delay early. timeout races an operation whose result is a capy::results against a deadline. A delay for a duration, or until a steady-clock time point, is a delay_awaitable. A delay until a time point on any other clock is a clock_delay_awaitable. On another clock, a wait-traits policy sets how long each underlying wait lasts before the delay reads the clock again. The default policy, wait_traits, waits for the full remaining time. A custom policy satisfies WaitTraits. See Delays and Timeouts and Reconnect with Backoff.

A signal_set waits for one of a registered set of signals, such as SIGINT. It derives from io_signal_set, which declares the wait operation. See Signal Handling.

A stream_file reads and writes a file in order, like a stream. A random_access_file reads and writes at offsets that the caller chooses. file_base holds the open flags that both types use. It also holds the seek origins that stream_file uses. See File I/O.

These types adopt a descriptor or handle that other code opened, and run its I/O on an io_context. On POSIX systems, a posix_stream_descriptor drives a descriptor such as a pipe, a FIFO, or a terminal. On Windows, win_stream_handle and win_random_access_handle drive overlapped handles. A win_object_handle waits on a Windows kernel object. See Native Descriptors and Handles.

A tls_context holds the certificates, keys, and protocol settings that a TLS stream uses. A tls_stream runs a TLS session over another stream. It encrypts the data it writes and decrypts the data it reads. openssl_stream and wolfssl_stream implement it with OpenSSL and with WolfSSL. A custom verification callback receives a verify_context. The wolfssl_supports_ functions report whether the WolfSSL build supports a feature. See TLS Encryption and TLS Context Configuration.

Operations report runtime failures as a std::error_code, alone or in a capy::results. error holds Corosio’s own error code, already_open, its one value. Most failures that Corosio detects itself use std::errc codes instead. make_error_code makes a std::error_code from an error value. An error from the OpenSSL error queue uses the category that openssl_category returns. OpenSSL errors from the system library, ERR_LIB_SYS, use std::system_category() instead. An error from wolfSSL_get_error uses the category that wolfssl_category returns. See Error Handling.

Each type in this section derives from the type with the same name minus the native_ prefix. It takes a tag value from I/O Context and I/O Backends as a template argument, as in native_tcp_socket<epoll>. The asynchronous operations of these types call that I/O backend directly, so the compiler can inline the whole call chain. native_io_context does the same for its event loop functions, such as run. A function that takes the base type also accepts the native object. Calls through the base type use virtual dispatch. Configuration shows how to construct a native_io_context with options.