[clang] 62a7562 - [docs] [C++20] [Modules] Add a workaround document for missing vtables

[Chuanqi Xu via cfe-commits]

Author: Chuanqi Xu
Date: 2024-07-10T11:23:14+08:00
New Revision: 62a7562b828ee9df6a41b6ce3dfda7c5511816a6

URL: https://github.com/llvm/llvm-project/commit/62a7562b828ee9df6a41b6ce3dfda7c5511816a6
DIFF: https://github.com/llvm/llvm-project/commit/62a7562b828ee9df6a41b6ce3dfda7c5511816a6.diff

LOG: [docs] [C++20] [Modules] Add a workaround document for missing vtables

Due to https://github.com/llvm/llvm-project/pull/75912 is reverted and
https://github.com/llvm/llvm-project/issues/70585 is reopened. It looks
riskful to fix the issue correctly before 19. So we provide a workaround
here to help people in this trouble as much as possible.

Added: 
    

Modified: 
    clang/docs/StandardCPlusPlusModules.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 1c3c4d319c0e1..cf0528e75e7f2 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -1092,6 +1092,74 @@ A high-level overview of support for standards features, including modules, can
 be found on the `C++ Feature Status <https://clang.llvm.org/cxx_status.html>`_
 page.
 
+Missing VTables for classes attached to modules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now the compiler may miss emitting the definition of vtables
+for classes attached to modules, if the definition of the class
+doesn't contain any key function in that module units
+(The key function is the first non-pure virtual function that is
+not inline at the point of class definition.)
+
+(Note: technically, the key function is not a thing for modules.
+We use the concept here for convinient.)
+
+For example,
+
+.. code-block:: c++
+
+  // layer1.cppm
+  export module foo:layer1;
+  struct Fruit {
+      virtual ~Fruit() = default;
+      virtual void eval() = 0;
+  };
+  struct Banana : public Fruit {
+      Banana() {}
+      void eval() override;
+  };
+
+  // layer2.cppm
+  export module foo:layer2;
+  import :layer1;
+  export void layer2_fun() {
+      Banana *b = new Banana();
+      b->eval();
+  }
+  void Banana::eval() {
+  }
+
+For the above example, we can't find the definition for the vtable of
+class ``Banana`` in any object files.
+
+The expected behavior is, for dynamic classes attached to named modules,
+the vtable should always be emitted to the module units the class attaches
+to.
+
+To workaround the problem, users can add the key function manually in the
+corresponding module units. e.g.,
+
+.. code-block:: c++
+
+  // layer1.cppm
+  export module foo:layer1;
+  struct Fruit {
+      virtual ~Fruit() = default;
+      virtual void eval() = 0;
+  };
+  struct Banana : public Fruit {
+      // Hack a key function to hint the compiler to emit the virtual table.
+      virtual void anchor();
+
+      Banana() {}
+      void eval() override;
+  };
+
+  void Banana::anchor() {}
+
+This is tracked by
+`#70585 <https://github.com/llvm/llvm-project/issues/70585>`_.
+
 Including headers after import is not well-supported
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~