From d231efe023a4a22ee2845ff6da3d3e1a733e433b Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Thu, 2 Nov 2017 20:35:11 +0100
Subject: hipe: Add doc sections about limitations

---
 lib/hipe/doc/src/hipe_app.xml | 73 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/lib/hipe/doc/src/hipe_app.xml b/lib/hipe/doc/src/hipe_app.xml
index e489d155c3..0f8511eb00 100644
--- a/lib/hipe/doc/src/hipe_app.xml
+++ b/lib/hipe/doc/src/hipe_app.xml
@@ -46,6 +46,79 @@
       <p>For on-line help in the Erlang shell, call <c>hipe:help()</c>. 
       Details on HiPE compiler options are given by <c>hipe:help_options()</c>.</p>
   </description>  
+  <section>
+    <title>Feature Limitations</title>
+    <p>
+      The HiPE compiler is in general compliant with the normal BEAM compiler,
+      with respect to semantic behavior. There are however features in the BEAM compiler
+      and the runtime system that have limited or no support for HiPE compiled modules.
+    </p>
+    <taglist>
+      <tag>Stack traces</tag>
+      <item><p>Stack traces returned from <seealso marker="erts:erlang#get_stacktrace/0">
+      <c>erlang:get_stacktrace/0</c></seealso> or as part of <c>'EXIT'</c> terms
+      can look incomplete if HiPE compiled functions are involved. Typically a stack trace
+      will contain only BEAM compiled functions or only HiPE compiled functions, depending
+      on where the exception was raised.</p>
+      <p>Source code line numbers in stack traces are also not supported by HiPE compiled functions.</p>
+      </item>
+
+      <tag>Tracing</tag>
+      <item><p>Modules compiled with HiPE have very limited support for runtime tracing
+      using <seealso marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seealso>.</p>
+      </item>
+
+      <tag>NIFs</tag>
+      <item><p>Modules compiled with HiPE can not call <seealso marker="erts:erlang#load_nif-2">
+      <c>erlang:load_nif/2</c></seealso> to load NIFs.</p>
+      </item>
+
+      <tag>-on_load</tag>
+      <item><p>Modules compiled with HiPE can not use
+      <seealso marker="doc/reference_manual:code_loading#on_load"><c>-on_load()</c></seealso>
+      directives.</p>
+      </item>
+    </taglist>
+
+  </section>
+  <section>
+    <title>Performance Limitations</title>
+    <p>
+      The HiPE compiler does in general produce faster code than the
+      BEAM compiler. There are however some situation when HiPE
+      compiled code will perform worse than BEAM code.
+    </p>
+    <taglist>
+      <tag>Mode switches</tag>
+      <item><p>Every time a process changes from executing code in a
+      HiPE compiled module to a BEAM compiled module (or vice versa),
+      it will do a mode switch. This involves a certain amount of
+      CPU overhead which can have a negative net impact if the
+      process is switching back and forth without getting enough done in
+      each mode.</p>
+      </item>
+
+      <tag>Optimization for <c>receive</c> with unique references</tag>
+      <item><p>The BEAM compiler can do an optimization when
+      a <c>receive</c> statement is <em>only</em> waiting for messages
+      containing a reference created before the receive. All messages
+      that existed in the queue when the reference was created will be
+      bypassed, as they cannot possibly contain the reference. HiPE
+      does not implement this optimization.</p>
+      <p>An example of this is when
+      <c>gen_server:call()</c> waits for the reply message.</p>
+      </item>
+
+      <tag>Unused list comprehensions</tag>
+      <item><p>List comprehensions used only for their side effects,
+      will be optimized by BEAM to not produce the unused result
+      list. This optimization is not done by HiPE.</p>
+      <pre>
+_ = [io:format("~p~n",[N]) || N &lt;- lists:seq(1,10)],</pre>
+      </item>
+
+    </taglist>
+  </section>
   <section>
     <title>SEE ALSO</title>
     <p>
-- 
cgit v1.2.3