C++ Module Support

[sgerbino]

Summary

Add support for C++20 modules to improve compile times and provide a modern interface for users.

Motivation

C++20 modules offer several benefits over traditional header-based inclusion:

• Faster compile times - Modules are parsed once and cached, eliminating redundant parsing of headers across translation units
• Better encapsulation - Implementation details can be hidden without relying on naming conventions or separate detail headers
• No macro leakage - Macros defined in module implementation don't affect importers
• Explicit dependency declarations - import statements make dependencies clear and enforceable

As a coroutine-based I/O library, Corosio would particularly benefit from modules since:

• Coroutine code is heavily templated with significant instantiation costs
• I/O operations involve many header dependencies (system headers, Boost.Asio concepts, TLS)
• Users typically include the entire library, amplifying redundant parsing

Proposed Approach

Phase 1: Primary Module Interface

Create a primary module interface that exports the public API:

// src/corosio.cppm
export module boost.corosio;

export import :io_context;
export import :socket;
export import :acceptor;
export import :resolver;
export import :read;
export import :write;
export import :tls;
// ...

Phase 2: Module Partitions

Split into logical partitions for better organization:

boost.corosio              - Primary module interface
boost.corosio:io_context   - io_context and scheduler
boost.corosio:socket       - Socket types
boost.corosio:acceptor     - TCP acceptor
boost.corosio:resolver     - DNS resolver
boost.corosio:read         - Read operations
boost.corosio:write        - Write operations
boost.corosio:tls          - TLS stream (WolfSSL)
boost.corosio:buffers      - Buffer types (any_bufref, consuming_buffers)

Phase 3: Dual Support

Maintain header support alongside modules for backwards compatibility:

// Users can choose:
import boost.corosio;           // Module import
// or
#include <boost/corosio.hpp>    // Traditional header

Dependencies

Corosio depends on:

• Boost.Capy - Coroutine primitives (task, when_all, async_run)
• Boost.URL - URL parsing
• Boost.System - Error codes

Module support should be coordinated with these dependencies, particularly Capy which is also a candidate for modules.

Tasks

• Coordinate with Boost.Capy module support (see cppalliance/capy#XX)
• Investigate CMake module support (requires CMake 3.28+)
• Audit headers for macro usage that would need adjustment
• Determine minimum compiler versions (GCC 14+, Clang 16+, MSVC 19.34+)
• Create module interface units (.cppm files)
• Handle platform-specific I/O (io_uring, epoll, kqueue) in module partitions
• Add module build configuration to CMakeLists.txt
• Update CI to test module builds (VF: Don't fail CI for modules)
• Document module usage
• Ensure Boost compatibility guidelines are followed

Considerations

Compiler Support

Compiler	Minimum Version	Notes
GCC	14+	Full module support
Clang	16+	Full module support
MSVC	19.34+	VS 2022 17.4+

Build System

CMake 3.28+ has native C++20 module support via CXX_MODULES target property. Earlier versions require workarounds.

Platform-Specific Code

Corosio has platform-specific I/O backends. Module partitions should be structured to handle:

• Linux: io_uring, epoll
• macOS/BSD: kqueue
• Windows: IOCP

Consider conditional module partitions or implementation modules for platform abstraction.

TLS Integration

The WolfSSL integration may require special handling since it wraps a C library. Ensure module boundaries don't break TLS functionality.

Boost Integration

Need to coordinate with Boost's broader modules strategy. Dependencies (Boost.System, Boost.URL) may not have module support yet, requiring careful handling at module boundaries.

References

• P1103R3 - Merging Modules
• CMake C++20 Modules
• Boost.Capy Modules Issue

[anarthal]

If you're going to provide dual support, it doesn't make sense to split things into partitions. I'd do a single .cppm file. I can try to submit a PR for this this weekend/next week.