[docs] Document that the modules can improve the linking time

[ChuanqiXu]

Summary

We found that the linking time decreases significantly after using modules. It is a big surprise and I feel like it is good to document it. So that other people whose project is pretty slow at linking time now may have stronger motivation to use modules.

[dblaikie]

I'm not sure I follow this - the comparison doesn't seem equal. If you wanted the modules-like code in non-modules, you could get it by having notDirectlyUsed declared-but-not-defined in the header file, and defined in the corresponding .cpp file, yeah?

[MaskRay]

This seems comparing different things... As mentioned, header files can be refactored to reduce the number of symbols as well.
I'd be curious to learn how linking time can be reduced significantly by deploying modules.

[ChuanqiXu]

I'd be curious to learn how linking time can be reduced significantly by deploying modules.

Oh, today I found the conclusion "significant decrease in link time time" was not responsible. Since I didn't recognize that our projects uses thinlto and thinlto cache. So there are too many factors and I can't say it reduces the linktime directly. And I'll try to do more precise analysis today.

And it would be great if you are interested. If you want to play with it. I think you can get started to apply the patch https://reviews.llvm.org/D138666 (this patch is for fun only.) to clang. Then you can find a sample project. The project would be best to have long link time and large and repeatedly included headers. Our project is close-sourced so I can't share it.

Then you can put the headers into a module unit:

// m.cppm
module;
#include "headers"
// ...
export module m;

Then for each .cc file, you can replace the headers with the modules by:

import m;

Note that if there are uses of macro in the source files, you need to extract them into a standalone header which contains macro definitions only. And let the source files include the standalone headers. Because the named modules can't export macros. (Or we can hack it in the compiler for simplicity). Finally remember to compile m.cppm to m.o and link it. (If there are bugs you can try to file an issue)

Then I think you are able to analysis the changes.

(Never mind if you don't want to do so many things)

In D138552#3947272, @dblaikie wrote:

I'm not sure I follow this - the comparison doesn't seem equal. If you wanted the modules-like code in non-modules, you could get it by having notDirectlyUsed declared-but-not-defined in the header file, and defined in the corresponding .cpp file, yeah?

Yeah.

This seems comparing different things... As mentioned, header files can be refactored to reduce the number of symbols as well.

It is true too.

It looks like my writing is misleading. Sorry for confusing. My point here is: with modules, the not directly used symbols wouldn't show up in the importee. And usuallythere would be many not directly used symbols in the header files. We need a clean re-design and some effort to move these not directly used items into .cpp files. It is not trivial in real world projects.

And another problem here is, without LTO, the function definitions in other TU can't be inlined. But now, the function definitions in the module interface can be imported to the importee as AvaialableExternally linkage with optimization. The AvaialableExternally linkage is a special linkage which aims for the IPO. And the AvaialableExternally entities would be removed in the middle end after inlining. (I know there are arguments to remove the function definition in the module file.) So if we move not directly used things in .cpp files, the performance will be hurt. But it is not the case for modules (at least for now).

[dblaikie]

And another problem here is, without LTO, the function definitions in other TU can't be inlined. But now, the function definitions in the module interface can be imported to the importee as AvaialableExternally linkage with optimization. The AvaialableExternally linkage is a special linkage which aims for the IPO. And the AvaialableExternally entities would be removed in the middle end after inlining. (I know there are arguments to remove the function definition in the module file.) So if we move not directly used things in .cpp files, the performance will be hurt. But it is not the case for modules (at least for now).

Yeah, I think if we're planning to minimize pcms to the point where they can't do code generation I guess we'll probably remove the indirect function definitions/not use available externally, and rely on (Thin)LTO to provide whole program optimization - so the guidance that modules reduces link time wouldn't be true in that case.

I think it's probably best to abandon this patch/not document/suggest that this is a benefit people should expect from modules if it's one that'd go away in the future anyway.

[ChuanqiXu]

In D138552#3951462, @dblaikie wrote:

And another problem here is, without LTO, the function definitions in other TU can't be inlined. But now, the function definitions in the module interface can be imported to the importee as AvaialableExternally linkage with optimization. The AvaialableExternally linkage is a special linkage which aims for the IPO. And the AvaialableExternally entities would be removed in the middle end after inlining. (I know there are arguments to remove the function definition in the module file.) So if we move not directly used things in .cpp files, the performance will be hurt. But it is not the case for modules (at least for now).

Yeah, I think if we're planning to minimize pcms to the point where they can't do code generation I guess we'll probably remove the indirect function definitions/not use available externally, and rely on (Thin)LTO to provide whole program optimization - so the guidance that modules reduces link time wouldn't be true in that case.

I think it's probably best to abandon this patch/not document/suggest that this is a benefit people should expect from modules if it's one that'd go away in the future anyway.

Got it. You're correct : )

clang/docs/StandardCPlusPlusModules.rst

 But we could still save the time for optimizations after IPO and the whole backend.
 
 Overall, at ``O0`` the implementations of functions defined in a module will not impact module users,
 but at higher optimization levels the definitions of such functions are provided to user compilations for the
 purposes of optimization (but definitions of these functions are still not included in the use's object file)-
 this means the build speedup at higher optimization levels may be lower than expected given ``O0`` experience, 
 but does provide by more optimization opportunities.
 
+Can modules speedup linking?
+----------------------------
+
+It is possible. Since the use of modules can reduce the symbols in the object files.
+
+Here is an example,
+
+.. code-block:: c++
+
+  // A.h
+  inline void notDirectlyUsed() {}
+  inline void DirectlyUsed() { notDirectlyUsed(); }
+
+  // A.cc
+  #include "A.h"
+  void foo() { DirectlyUsed(); }
+
+then compile it and look the generated symbol with the following commands
+
+.. code-block:: console
+
+  $ clang++ -std=c++20 A.cc -c -o A.o
+  $ nm -C A.o
+  0000000000000000 W DirectlyUsed()
+  0000000000000000 W notDirectlyUsed()
+  0000000000000000 T foo()
+
+now let's check the result after using modules with the following example:
+
+.. code-block:: c++
+
+  // A.cppm
+  export module A;
+  void notDirectlyUsed() {}
+  export void DirectlyUsed() { notDirectlyUsed(); }
+  
+  // A.cc
+  #include "A.h"
+  void foo() { DirectlyUsed(); }
+
+compile it with the following commands:
+
+.. code-block:: console
+
+  $ clang++ -std=c++20 A.cppm --precompile -o A.pcm
+  $ clang++ -std=c++20 A.cc -fprebuilt-module-path=. -c -o A.o
+  $ nm -C A.o
+  0000000000000000 t _GLOBAL__sub_I_Use.cc
+  0000000000000000 T foo()
+                   U _ZGIW1A
+                   U _ZW1A12DirectlyUsedv
+
+First we can find that there are 2 additional symbols ``_GLOBAL__sub_I_Use`` and
+``_ZGIW1A``. These 2 symbols are used to initialize the current object file and
+the module A.
+
+The interesting part here is that there is not the symbol for ``notDirectlyUsed``.
+In a real world project, the number of ``notDirectlyUsed`` symbols should
+usually be much more than the ``DirectlyUsed`` ones.
+
+So that we can reduce many symbols in the object files and so we can speedup linking
+by using modules. Note that things may be better with optimizations, since the
+``DirectlyUsed`` ones may be optimized out.
+
 Interoperability with Clang Modules
 -----------------------------------
 
 We **wish** to support clang modules and standard c++ modules at the same time,
 but the mixed using form is not well used/tested yet.
 
 Please file new github issues as you find interoperability problems.