Merge PR-1618 from sverker/sverker/hipe-doc-limitations OTP-14767

Document HiPE limitations

1 files changed, 66 insertions, 0 deletions

diff --git a/lib/hipe/doc/src/hipe_app.xml b/lib/hipe/doc/src/hipe_app.xml
index e489d155c3..9299c6d73f 100644
--- a/lib/hipe/doc/src/hipe_app.xml
+++ b/lib/hipe/doc/src/hipe_app.xml
@@ -47,6 +47,72 @@
       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>Erlang call trace is not supported by HiPE. Calling
+      <seealso marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern({M,F,A}, ...)</c></seealso>
+      does not have any effect on HiPE compiled modules.</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>
+
+    </taglist>
+  </section>
+  <section>
     <title>SEE ALSO</title>
     <p>
       <seealso marker="stdlib:c">c(3)</seealso>,