[llvm] [Utils] Identity map module-level debug info on first use in CloneFunction* (PR #118627)

[Artem Pianykh via llvm-commits]

================
@@ -136,6 +138,18 @@ inline RemapFlags operator|(RemapFlags LHS, RemapFlags RHS) {
 /// alternate \a ValueToValueMapTy and \a ValueMaterializer and returns a ID to
 /// pass into the schedule*() functions.
 ///
+/// NOTE: \c IdentityMD is used by CloneFunction* to directly specify metadata
+/// that should be identity mapped (and hence not cloned). The metadata will be
+/// identity mapped in \c VM on first use. There are several reasons for doing
+/// it this way rather than eagerly identity mapping metadata nodes in \c VM:
+/// 1. Mapping metadata is not cheap, particularly because of tracking.
+/// 2. When cloning a Function we identity map lots of global module-level
+///    metadata to avoid cloning it, while only a fraction of it is actually
+///    used by the function. Mapping on first use is a lot faster for modules
+///    with meaningful amount of debug info.
+/// 3. Eagerly identity mapping metadata makes it harder to cache module-level
+///    data (e.g. a set of metadata nodes in a \a DICompileUnit).
+///
----------------
artempyanykh wrote:

This is fair! I moved the NOTE to `Cloning.h/FindDebugInfoToIdentityMap`. I don't think there's a single best place in Cloning.h to attach this NOTE to, but FindDebugInfoToIdentityMap feels like a reasonable one.

https://github.com/llvm/llvm-project/pull/118627