[module] (original) (raw)

10 Modules [module]

10.1 Module units and purviews [module.unit]

A module unit is a translation unit that contains a module-declaration.

A named module is the collection of module units with the same module-name.

The identifiers module and importshall not appear as identifier_s_in a module-name or module-partition.

All module-names either beginning with an identifierconsisting of std followed by zero or more digits or containing a reserved identifier ([lex.name]) are reserved and shall not be specified in a module-declaration; no diagnostic is required.

If any identifier in a reserved module-nameis a reserved identifier, the module name is reserved for use by C++ implementations; otherwise it is reserved for future standardization.

A module interface unit is a module unit whosemodule-declaration starts with export-keyword; any other module unit is a module implementation unit.

A named module shall contain exactly one module interface unit with no module-partition, known as theprimary module interface unit of the module; no diagnostic is required.

A module partition is a module unit whose module-declaration contains a module-partition.

A named module shall not contain multiple module partitions with the same module-partition.

All module partitions of a module that are module interface units shall be directly or indirectly exported by the primary module interface unit ([module.import]).

No diagnostic is required for a violation of these rules.

[Note 1:

Module partitions can be imported only by other module units in the same module.

The division of a module into module units is not visible outside the module.

— _end note_]

[Example 1:

Translation unit #1:export module A;export import :Foo;export int baz();

Translation unit #2:export module A:Foo;import :Internals;export int foo() { return 2 * (bar() + 1); }

Translation unit #3:module A:Internals;int bar();

Translation unit #4:module A;import :Internals;int bar() { return baz() - 10; } int baz() { return 30; }

Module A contains four translation units:

• a primary module interface unit,
• a module partition A:Foo, which is a module interface unit forming part of the interface of module A,
• a module partition A:Internals, which does not contribute to the external interface of module A, and
• a module implementation unit providing a definition of bar and baz, which cannot be imported because it does not have a partition name.

— _end example_]

A module unit purview is the sequence of token_s_starting at the module-declarationand extending to the end of the translation unit.

The purviewof a named module M is the set of module unit purviews of M's module units.

The global module is the collection of allglobal-module-fragment_s_and all translation units that are not module units.

Declarations appearing in such a context are said to be in the purview of the global module.

[Note 2:

The global module has no name, no module interface unit, and is not introduced by any module-declaration.

— _end note_]

A module is either a named module or the global module.

A declaration is attached to a module as follows:

• Otherwise, the declaration is attached to the module in whose purview it appears.

A module-declarationthat contains neither an _export-keyword_nor a module-partitionimplicitly imports the primary module interface unit of the module as if by a module-import-declaration.

[Example 2:

Translation unit #1:module B:Y; int y();

Translation unit #2:export module B;import :Y; int n = y();

Translation unit #3:module B:X1; int &a = n;

Translation unit #4:module B:X2; import B;int &b = n;

Translation unit #5:module B; int &c = n; — _end example_]

10.2 Export declaration [module.interface]

An export-declaration shall inhabit a namespace scope and appear in the purview of a module interface unit.

An export-declaration shall not appear directly or indirectly within an unnamed namespace or a private-module-fragment.

[Note 1:

An export-declaration does not establish a scope.

— _end note_]

A declaration is exported if it is declared within an export-declaration and inhabits a namespace scope or it is

• a namespace-definition that contains an exported declaration, or
• a declaration within a header unit ([module.import]) that introduces at least one name.

If an exported declaration is not within a header unit, it shall not declare a name with internal linkage.

[Example 1:

Source file "a.h":export int x;

Translation unit #1:module;#include "a.h" export module M;export namespace {} namespace { export int a2; } export static int b; export int f(); export namespace N { } export using namespace N; — _end example_]

If an exported declaration is a using-declaration ([namespace.udecl]) and is not within a header unit, all entities to which all of theusing-declarators ultimately refer (if any) shall have been introduced with a name having external linkage.

[Example 2:

Source file "b.h":int f();

Importable header "c.h":int g();

Translation unit #1:export module X;export int h();

Translation unit #2:module;#include "b.h" export module M;import "c.h";import X;export using ::f, ::g, ::h; struct S;export using ::S; namespace N { export int h();static int h(int); } export using N::h; — _end example_]

[Note 2:

These constraints do not apply to type names introduced by typedef declarations and alias-declarations.

[Example 3: export module M;struct S;export using T = S; — _end example_]

— _end note_]

A redeclaration of an entity Xis implicitly exported if X was introduced by an exported declaration; otherwise it shall not be exported unless it is a namespace.

[Example 4: export module M;struct S { int n; };typedef S S;export typedef S S; export struct S; namespace N { void f();} namespace N { export void g();} — _end example_]

[Note 3:

Names introduced by exported declarations have either external linkage or no linkage; see [basic.link].

Namespace-scope declarations exported by a module can be found by name lookup in any translation unit importing that module ([basic.lookup]).

Class and enumeration member names can be found by name lookup in any context in which a definition of the type is reachable.

— _end note_]

[Example 5:

Interface unit of M:export module M;export struct X { static void f();struct Y { };};namespace { struct S { };} export void f(S); struct T { };export T id(T); export struct A; export auto rootFinder(double a) { return [=](double x) { return (x + a/x)/2; };} export const int n = 5;

Implementation unit of M:module M;struct A { int value;};

Main program:import M;int main() { X::f(); X::Y y; auto f = rootFinder(2); return A{45}.value; } — _end example_]

[Note 4:

[Example 6: export module M;int g;export namespace N { int x; using ::g; } — _end example_]

— _end note_]

10.3 Import declaration [module.import]

A module-import-declarationshall inhabit the global namespace scope.

A module-import-declaration imports a set of translation units determined as described below.

[Note 1:

Namespace-scope declarations exported by the imported translation units can be found by name lookup ([basic.lookup]) in the importing translation unit and declarations within the imported translation units become reachable ([module.reach]) in the importing translation unit after the import declaration.

— _end note_]

A module-import-declaration that specifies a module-name Mimports all module interface units of M.

A module-import-declaration that specifies a module-partition shall only appear after the module-declaration in a module unit of some module M.

Such a declaration imports the so-named module partition of M.

A module-import-declaration that specifies a H imports a synthesized , which is a translation unit formed by applying phases 1 to 7 of translation ([lex.phases]) to the source file or header nominated by H, which shall not contain a module-declaration.

[Note 2:

A header unit is a separate translation unit with an independent set of defined macros.

All declarations within a header unit are implicitly exported ([module.interface]), and are attached to the global module ([module.unit]).

— _end note_]

An is a member of animplementation-defined set of headers that includes all importable C++ library headers ([headers]).

H shall identify an importable header.

Given two such module-import-declarations:

• if their s identify different headers or source files ([cpp.include]), they import distinct header units;
• otherwise, if they appear in the same translation unit, they import the same header unit;
• otherwise, it is unspecified whether they import the same header unit.
  [Note 3:
  It is therefore possible that multiple copies exist of entities declared with internal linkage in an importable header.
  — _end note_]

[Note 4:

A module-import-declaration nominating a is also recognized by the preprocessor, and results in macros defined at the end of phase 4 of translation of the header unit being made visible as described in [cpp.import].

Any other module-import-declarationdoes not make macros visible.

— _end note_]

A declaration of a name with internal linkage is permitted within a header unit despite all declarations being implicitly exported ([module.interface]).

[Note 5:

A definition that appears in multiple translation units cannot in general refer to such names ([basic.def.odr]).

— _end note_]

A header unit shall not contain a definition of a non-inline function or variable whose name has external linkage.

When a module-import-declaration imports a translation unit T, it also imports all translation units imported by exported module-import-declaration_s_in T; such translation units are said to be exported by T.

Additionally, when a module-import-declarationin a module unit of some module M imports another module unit U of M, it also imports all translation units imported by non-exported module-import-declaration_s_in the module unit purview of U.85

These rules can in turn lead to the importation of yet more translation units.

[Note 6:

Such indirect importation does not make macros available, because a translation unit is a sequence of tokens in translation phase 7 ([lex.phases]).

Macros can be made available by directly importing header units as described in [cpp.import].

— _end note_]

A module implementation unit shall not be exported.

[Example 1:

Translation unit #1:module M:Part;

Translation unit #2:export module M;export import :Part; — _end example_]

A module implementation unit of a module Mthat is not a module partition shall not contain a module-import-declarationnominating M.

[Example 2: module M;import M; — _end example_]

A translation unit has an interface dependency on a translation unit Uif it contains a declaration (possibly a module-declaration) that imports U or if it has an interface dependency on a translation unit that has an interface dependency on U.

A translation unit shall not have an interface dependency on itself.

[Example 3:

Interface unit of M1:export module M1;import M2;

Interface unit of M2:export module M2;import M3;

Interface unit of M3:export module M3;import M1; — _end example_]

10.4 Global module fragment [module.global.frag]

[Note 1:

Prior to phase 4 of translation, only preprocessing directives can appear in the declaration-seq ([cpp.pre]).

— _end note_]

A global-module-fragment specifies the contents of theglobal module fragment for a module unit.

The global module fragment can be used to provide declarations that are attached to the global module and usable within the module unit.

A declaration D is decl-reachable from a declaration Sin the same translation unit if

• D does not declare a function or function template andS contains anid-expression,namespace-name,type-name,template-name, orconcept-namenaming D, or
• D declares a function or function template that is named by an expression ([basic.def.odr]) appearing in S, or
• S contains a dependent call E ([temp.dep]) and D is found by any name lookup performed for an expression synthesized from Eby replacing each type-dependent argument or operand with a value of a placeholder type with no associated namespaces or entities, or
  [Note 2:
  This includes the lookup for operator== performed when considering rewriting an != expression, the lookup for operator<=>performed when considering rewriting a relational comparison, and the lookup for operator!=when considering whether an operator== is a rewrite target.
  — _end note_]
• S contains an expression that takes the address of an overload set ([over.over]) that contains D and for which the target type is dependent, or
• there exists a declaration M that is not a namespace-definitionfor which M is decl-reachable from S and either
  • D is decl-reachable from M, or
  • D and M declare the same entity, and D neither is a friend declaration nor inhabits a block scope, or
  • D declares a namespace N and M is a member of N, or
  • one of D and M declares a class or class template Cand the other declares a member or friend of C, or
  • one of D and M declares an enumeration Eand the other declares an enumerator of E, or
  • D declares a function or variable and M is declared in D,86or
  • one of D and M declares a template and the other declares a partial or explicit specialization or an implicit or explicit instantiation of that template, or
  • M declares a class template and D is a deduction guide for that template, or
  • one of D and M declares a class or enumeration type and the other introduces a typedef name for linkage purposes for that type.

In this determination, it is unspecified

• whether a reference to analias-declaration,typedef declaration,using-declaration, ornamespace-alias-definitionis replaced by the declarations they name prior to this determination,
• whether a simple-template-idthat does not denote a dependent type and whose template-name names an alias template is replaced by its denoted type prior to this determination,
• whether a decltype-specifierthat does not denote a dependent type is replaced by its denoted type prior to this determination, and
• whether a non-value-dependent constant expression is replaced by the result of constant evaluation prior to this determination.

[Note 3:

A discarded declaration is neither reachable nor visible to name lookup outside the module unit, nor in template instantiations whose points of instantiation ([temp.point]) are outside the module unit, even when the instantiation context ([module.context]) includes the module unit.

— _end note_]

[Example 1: const int size = 2;int ary1[size]; constexpr int identity(int x) { return x; } int ary2[identity(2)]; template<typename> struct S;template<typename, int> struct S2;constexpr int g(int);template<typename T, int N>S<S2<T, g(N)>> f(); template<int N> void h() noexcept(g(N) == N); — _end example_]

[Example 2:

Source file "foo.h":namespace N { struct X {};int d();int e();inline int f(X, int = d()) { return e(); } int g(X);int h(X);}

Module M interface:module;#include "foo.h" export module M;template<typename T> int use_f() { N::X x; return f(x, 123); } template<typename T> int use_g() { N::X x; return g((T(), x)); } template<typename T> int use_h() { N::X x; return h((T(), x)); } int k = use_h<int>();

Module M implementation:module M;int a = use_f<int>(); int b = use_g<int>(); int c = use_h<int>(); — _end example_]

10.5 Private module fragment [module.private.frag]

A private-module-fragment shall appear only in a primary module interface unit ([module.unit]).

A module unit with a private-module-fragmentshall be the only module unit of its module; no diagnostic is required.

[Note 1:

A private-module-fragment ends the portion of the module interface unit that can affect the behavior of other translation units.

A private-module-fragment allows a module to be represented as a single translation unit without making all of the contents of the module reachable to importers.

The presence of a private-module-fragment affects:

• the point by which the definition of an inline function or variable is required ([dcl.inline]),
• the point by which the definition of an exported function with a placeholder return type is required ([dcl.spec.auto]),
• whether a declaration is required not to be an exposure ([basic.link]),
• where definitions for inline functions and templates must appear ([basic.def.odr], [dcl.inline], [temp.pre]),
• the instantiation contexts of templates instantiated before it ([module.context]), and
• the reachability of declarations within it ([module.reach]).

— _end note_]

[Example 1: export module A;export inline void fn_e(); inline void fn_m(); static void fn_s();export struct X;export void g(X *x) { fn_s(); } export X *factory(); module :private;struct X {}; X *factory() { return new X ();} void fn_e() {} void fn_m() {} void fn_s() {} — _end example_]

10.6 Instantiation context [module.context]

The instantiation context is a set of points within the program that determines which declarations are found by argument-dependent name lookup ([basic.lookup.argdep]) and which are reachable ([module.reach]) in the context of a particular declaration or template instantiation.

During the implicit definition of a defaulted function ([special], [class.compare.default]), the instantiation context is the union of the instantiation context from the definition of the class and the instantiation context of the program construct that resulted in the implicit definition of the defaulted function.

During the implicit instantiation of a template whose point of instantiation is specified as that of an enclosing specialization ([temp.point]), the instantiation context is the union of the instantiation context of the enclosing specialization and, if the template is defined in a module interface unit of a module Mand the point of instantiation is not in a module interface unit of M, the point at the end of thedeclaration-seq of the primary module interface unit of M(prior to the private-module-fragment, if any).

During the implicit instantiation of a template that is implicitly instantiated because it is referenced from within the implicit definition of a defaulted function, the instantiation context is the instantiation context of the defaulted function.

During the instantiation of any other template specialization, the instantiation context comprises the point of instantiation of the template.

In any other case, the instantiation context at a point within the program comprises that point.

[Example 1:

Translation unit #1:export module stuff;export template<typename T, typename U> void foo(T, U u) { auto v = u; } export template<typename T, typename U> void bar(T, U u) { auto v = *u; }

Translation unit #2:export module M1;import "defn.h"; import stuff;export template<typename T> void f(T t) { X x; foo(t, x);}

Translation unit #3:export module M2;import "decl.h"; import stuff;export template<typename T> void g(T t) { X *x; bar(t, x);}

Translation unit #4:import M1;import M2;void test() { f(0); g(0);}

The call to f(0) is valid; the instantiation context of foo<int, X> comprises

• the point at the end of translation unit #1,
• the point at the end of translation unit #2, and
• the point of the call to f(0),

so the definition of X is reachable ([module.reach]).

It is unspecified whether the call to g(0) is valid: the instantiation context of bar<int, X> comprises

• the point at the end of translation unit #1,
• the point at the end of translation unit #3, and
• the point of the call to g(0),

so the definition of X need not be reachable, as described in [module.reach].

— _end example_]

10.7 Reachability [module.reach]

A translation unit U isnecessarily reachablefrom a point P ifU is a module interface unit on which the translation unit containing Phas an interface dependency, or the translation unit containing P imports U, in either case prior to P ([module.import]).

[Note 1:

While module interface units are reachable even when they are only transitively imported via a non-exported import declaration, namespace-scope names from such module interface units are not found by name lookup ([basic.lookup]).

— _end note_]

All translation units that are necessarily reachable arereachable.

Additional translation units on which the point within the program has an interface dependency may be considered reachable, but it is unspecified which are and under what circumstances.87

[Note 2:

It is advisable to avoid depending on the reachability of any additional translation units in programs intending to be portable.

— _end note_]

A declaration D isreachable from a point P if

• D appears prior to P in the same translation unit, or
• D is not discarded ([module.global.frag]), appears in a translation unit that is reachable from P, and does not appear within a private-module-fragment.

A declaration is reachableif it is reachable from any point in the instantiation context ([module.context]).

[Note 3:

Whether a declaration is exported has no bearing on whether it is reachable.

— _end note_]

The accumulated properties of all reachable declarations of an entity within a context determine the behavior of the entity within that context.

[Note 4:

These reachable semantic properties include type completeness, type definitions, initializers, default arguments of functions or template declarations, attributes, names bound, etc.

Since default arguments are evaluated in the context of the call expression, the reachable semantic properties of the corresponding parameter types apply in that context.

[Example 1:

Translation unit #1:export module M:A;export struct B;

Translation unit #2:module M:B;struct B { operator int();};

Translation unit #3:module M:C;import :A; B b1;

Translation unit #4:export module M;export import :A;import :B; B b2;export void f(B b = B());

Translation unit #5:import M; B b3; void g() { f(); } — _end example_]

— _end note_]

[Note 5:

Declarations of an entity can be reachable even where they cannot be found by name lookup.

— _end note_]

[Example 2:

Translation unit #1:export module A;struct X {};export using Y = X;

Translation unit #2:import A; Y y; X x; — _end example_]