Skip to content

Commit 85b113c

Browse files
authored
[Doc] [C++20] [Modules] Clarify the reachability of internal partition units (#102572)
Motivated by #101348 Although I don't want the tool's doc to explain the standard's wording, the wording itself has some unspecified thing. So I feel it will be helpful to make it clear. At least it may help us receive less invalid issue reports.
1 parent 2ab910c commit 85b113c

File tree

1 file changed

+52
-0
lines changed

1 file changed

+52
-0
lines changed

clang/docs/StandardCPlusPlusModules.rst

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1230,6 +1230,58 @@ parsing their headers, those should be included after the import. If the
12301230
imported modules don't provide such a header, one can be made manually for
12311231
improved compile time performance.
12321232

1233+
Reachability of internal partition units
1234+
----------------------------------------
1235+
1236+
The internal partition units are sometimes called implementation partition units in other documentation.
1237+
However, the name may be confusing since implementation partition units are not implementation
1238+
units.
1239+
1240+
According to `[module.reach]p1 <https://eel.is/c++draft/module.reach#1>`_ and
1241+
`[module.reach]p2 <https://eel.is/c++draft/module.reach#2>`_ (from N4986):
1242+
1243+
A translation unit U is necessarily reachable from a point P if U is a module
1244+
interface unit on which the translation unit containing P has an interface
1245+
dependency, or the translation unit containing P imports U, in either case
1246+
prior to P.
1247+
1248+
All translation units that are necessarily reachable are reachable. Additional
1249+
translation units on which the point within the program has an interface
1250+
dependency may be considered reachable, but it is unspecified which are and
1251+
under what circumstances.
1252+
1253+
For example,
1254+
1255+
.. code-block:: c++
1256+
1257+
// a.cpp
1258+
import B;
1259+
int main()
1260+
{
1261+
g<void>();
1262+
}
1263+
1264+
// b.cppm
1265+
export module B;
1266+
import :C;
1267+
export template <typename T> inline void g() noexcept
1268+
{
1269+
return f<T>();
1270+
}
1271+
1272+
// c.cppm
1273+
module B:C;
1274+
template<typename> inline void f() noexcept {}
1275+
1276+
The internal partition unit ``c.cppm`` is not necessarily reachable by
1277+
``a.cpp`` because ``c.cppm`` is not a module interface unit and ``a.cpp``
1278+
doesn't import ``c.cppm``. This leaves it up to the compiler to decide if
1279+
``c.cppm`` is reachable by ``a.cpp`` or not. Clang's behavior is that
1280+
indirectly imported internal partition units are not reachable.
1281+
1282+
The suggested approach for using an internal partition unit in Clang is
1283+
to only import them in the implementation unit.
1284+
12331285
Known Issues
12341286
------------
12351287

0 commit comments

Comments
 (0)