Cross-Platform I/O (io_uring / IOCP)
Relevant source files
The following files were used as context for generating this wiki page:
The Cross-Platform I/O system provides a unified interface for high-performance asynchronous operations across different operating systems. It abstracts the underlying platform-specific mechanisms, specifically Linux io_uring and Windows I/O Completion Ports (IOCP), to enable efficient network and file operations within a coroutine-based environment.
This system manages file descriptors, socket handles, and asynchronous event loops. By encapsulating platform-specific headers and logic, it ensures that higher-level components like HttpServer and HttpClient can perform non-blocking I/O without direct dependency on the host OS.
Sources: include/HXLibs/platform/EventLoopApi.hpp, include/HXLibs/platform/LocalFdApi.hpp, include/HXLibs/platform/SocketFdApi.hpp
Platform Architecture and Abstractions
The library uses conditional compilation to define platform-specific types and include necessary system headers. This approach hides the differences between Linux file descriptors and Windows handles.
File and Socket Descriptor Types
The library defines LocalFdType to represent local file system identifiers and socket handles.
| Platform | Underlying Type | Invalid Descriptor Constant |
|---|---|---|
| Linux | int | -1 |
| Windows | HANDLE (void*) | INVALID_HANDLE_VALUE |
Sources: include/HXLibs/platform/LocalFdApi.hpp:39-44, include/HXLibs/platform/LocalFdApi.hpp:67-97
I/O Operations Flow
The following diagram illustrates how the system dispatches requests to the appropriate platform backend:
Note: The flow shows how asynchronous requests transition from submission to completion notification across platforms.
Linux Backend: io_uring
On Linux, the library integrates liburing.h to utilize the io_uring interface. This interface uses shared memory rings between the kernel and user space to reduce system call overhead.
Submission and Completion Rings
The io_uring structure maintains two primary rings:
- Submission Queue (SQ): Where the application places Submission Queue Entries (SQEs) describing the I/O operation (e.g.,
read,write,accept). - Completion Queue (CQ): Where the kernel places Completion Queue Entries (CQEs) containing the result of the operation.
Sources: lib/liburing/include/liburing.h:476-508
Key Operations
Linux I/O uses specific flags for efficiency:
O_DIRECT: Reduces memory copying between user space and the kernel (currently marked as experimental inCMakeLists.txt).O_CLOEXEC: Ensures file descriptors do not inherit to child processes.IORING_SETUP_SQPOLL: Enables a kernel thread to poll the submission queue, further reducingio_uring_entercalls.
Sources: include/HXLibs/platform/LocalFdApi.hpp:30-36, lib/liburing/include/liburing.h:161, CMakeLists.txt:13
Windows Backend: IOCP
On Windows, the library utilizes I/O Completion Ports (IOCP) and the Win32 Overlapped I/O model.
Win32 API Initialization
The library uses InitWin32Api to manage the lifecycle of the Windows Socket (WSA) environment. It calls WSAStartup during initialization and WSACleanup during destruction. This class is invoked within the EventLoop constructor using a thread-safe ensure() method.
Sources: include/HXLibs/platform/EventLoopApi.hpp:85-108
Function Pointers and Extensions
Certain high-performance Windows functions are not exported directly and must be loaded at runtime. The ConnectExLoader class fetches the ConnectEx function pointer via WSAIoctl using the SIO_GET_EXTENSION_FUNCTION_POINTER control code.
Sources: include/HXLibs/platform/EventLoopApi.hpp:52-83
Win32 File Parameters
Windows requires specific flags to enable asynchronous behavior:
FILE_FLAG_OVERLAPPED: Mandatory flag for IOCP compatibility.GENERIC_READ/GENERIC_WRITE: Access permissions mapping to LinuxOpenMode.Win32FileParamsBuilder: A helper class that maps the unifiedOpenModeto the complexaccess,creation, andflagsparameters required byCreateFileW.
Sources: include/HXLibs/platform/LocalFdApi.hpp:115-171
Universal Open Modes
To maintain cross-platform consistency, the system defines a unified OpenMode enum. These enums are mapped to native flags for both open() (Linux) and CreateFileW (Windows).
| Unified Mode | Linux Mapping | Windows Mapping (via Builder) |
|---|---|---|
Read | O_RDONLY | GENERIC_READ, OPEN_EXISTING |
Write | O_WRONLY | O_TRUNC | O_CREAT | GENERIC_WRITE, CREATE_ALWAYS |
Append | O_WRONLY | O_APPEND | O_CREAT | FILE_APPEND_DATA, OPEN_ALWAYS |
Directory | O_RDONLY | O_DIRECTORY | GENERIC_READ, FILE_FLAG_BACKUP_SEMANTICS |
Sources: include/HXLibs/platform/LocalFdApi.hpp:46-52, include/HXLibs/platform/LocalFdApi.hpp:126-166
Summary
The Cross-Platform I/O system provides the necessary infrastructure to support high-performance, non-blocking I/O across Linux and Windows. By abstracting io_uring and IOCP behind a common API, the library enables a consistent coroutine-based programming model while leveraging the most efficient I/O mechanisms available on each respective platform.
Sources: include/HXLibs/platform/EventLoopApi.hpp, include/HXLibs/platform/LocalFdApi.hpp, include/HXLibs/platform/SocketFdApi.hpp