doc FAQ: add items for common code causes of 'Mismatched' errors

(when there is no fault in the code).

diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml
index 414ac1364babbf25de22caf9d716b2b627487fd2..4179a62ac1d70d112429f6abe1498393f8cd4feb 100644 (file)
--- a/docs/xml/FAQ.xml
+++ b/docs/xml/FAQ.xml
@@ -486,9 +486,62 @@ int main(void)
   </answer>
 </qandaentry>
 
-</qandadiv>
+<qandaentry id="faq.mismatches">
+  <question id="q-mismatches">
+    <para>Why does Memcheck report many
+      &quot;Mismatched free() / delete / delete []&quot; errors when
+      my code is correct?</para>
+  </question>
+  <answer id="a-mismatches">
+    <para>There are two possible causes of this.</para>
+
+    <para>First, check if you are using an optimized build of Google
+      tcmalloc (part of Google perftools). This library uses a single
+      alias for free/scalar delete/array delete as an unmeasurable
+      micro-optimization. There is simply no way for Memcheck to tell
+      which of these was originally used. There are a few possible
+      workarounds.
+      <itemizedlist>
+        <listitem>
+          <para>Build tcmalloc with &quot;CPPFLAGS=-DTCMALLOC_NO_ALIASES&quot;
+            (best).</para>
+        </listitem>
+        <listitem>
+          <para>Use a debug build of tcmalloc (debug builds turn off the alias
+            micro-optimization).</para>
+        </listitem>
+        <listitem>
+          <para>Do not link with tcmalloc for the builds that you use for
+            Memecheck testing.</para>
+        </listitem>
+      </itemizedlist>
+    </para>
 
+    <para>Second, if you are replacing operator new or operator delete
+      make sure that the compiler does not perform optimizations such as
+      inlining on calls to these functions. Such optimizations can
+      prevent Memcheck from correctly identifying the allocator or
+      deallocator that is being used.</para>
+
+    <para>The following two code snippets show how you can do this with
+      GCC and LLVM (clang).</para>
+
+<programlisting>
+  // GCC
+  void operator delete(void*) noexcept __attribute__((__externally_visible__));
+</programlisting>
 
+<programlisting>
+  // LLVM (clang)
+  __attribute__((__visibility__(&quot;default&quot;))) void operator delete(void*) noexcept;
+</programlisting>
+
+    <para>If all else fails, you might have to use &quot;--show-mismatched-frees=no&quot;
+    </para>
+  </answer>
+</qandaentry>
+
+</qandadiv>
 
 <!-- Miscellaneous -->
 <qandadiv id="faq.misc" xreflabel="Miscellaneous">