Module Partition

A C++ module partition is a structural mechanism introduced in C++20 that allows a single module to be divided across multiple translation units. Partitions enable the logical separation of a module’s declarations and definitions into distinct files while presenting a single, unified module to external consumers. They are strictly internal to the owning module; external code can only import the primary module, never its individual partitions.

The syntactic delimiter for a partition is a colon (:), formatted as PrimaryModuleName:PartitionName.

There are two distinct types of module partitions: Interface Partitions and Implementation Partitions.

Interface Partitions

An interface partition contains declarations (and potentially definitions) that are intended to be part of the primary module’s public API.

It is declared using the export module keywords followed by the partition name.

// File: math_operations_add.cpp (Interface Partition)
export module math:addition;

export int add(int a, int b) {
    return a + b;
}

For the contents of an interface partition to be visible to external consumers, the primary module interface file must explicitly re-export it using export import :PartitionName;.

Implementation Partitions

An implementation partition contains internal logic, helper functions, or definitions that are strictly private to the module. It does not contribute to the public API.

It is declared using the module keyword (without export) followed by the partition name.

// File: math_operations_internal.cpp (Implementation Partition)
module math:internal_helpers;

bool is_positive(int a) {
    return a > 0;
}

Implementation partitions can be imported by the primary module interface or by other partitions within the same module using import :PartitionName;. They cannot be exported.

The Primary Module Interface

The primary module interface acts as the aggregator for all partitions. It defines the module’s name and dictates exactly what is exposed to the consumer.

// File: math.cpp (Primary Module Interface)
export module math;

// Re-export the interface partition to the public API
export import :addition; 

// Import the implementation partition for internal use only
import :internal_helpers; 

export int add_positive_only(int a, int b) {
    if (is_positive(a) && is_positive(b)) {
        return add(a, b);
    }
    return 0;
}

Architectural Rules and Constraints

1. Internal Visibility: The syntax import :PartitionName; is only valid within translation units belonging to the same primary module. External translation units must use import PrimaryModuleName;.
2. Export Obligation: If an interface partition (export module M:P;) exists, it must be exported (export import :P;) by the primary module interface. Failure to do so renders the program ill-formed.
3. No Sub-partitions: The partition syntax does not support nesting. A declaration like export module math:addition:integers; is syntactically invalid.
4. Acyclic Dependencies: Partitions within the same module form a dependency graph that must be a Directed Acyclic Graph (DAG). Cyclic imports between partitions (e.g., :A imports :B, and :B imports :A) are ill-formed.
5. Implicit Imports: An implementation unit of a module (e.g., module math;) implicitly imports the primary module interface, but it does not implicitly import the module’s partitions. Partitions must be explicitly imported where needed.

Master C++ with Deep Grasping Methodology!

Learn More