From 1c82039a53fa0885fc8a292a841c6939e04a0da2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Tue, 7 Jun 2016 16:16:26 +0200
Subject: Add a myth about NIFs

Thanks to Max Lapshin for suggesting this myth.
---
 system/doc/efficiency_guide/myths.xml | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

(limited to 'system/doc/efficiency_guide/myths.xml')

diff --git a/system/doc/efficiency_guide/myths.xml b/system/doc/efficiency_guide/myths.xml
index 7e2f3c8465..d6cb27ddf0 100644
--- a/system/doc/efficiency_guide/myths.xml
+++ b/system/doc/efficiency_guide/myths.xml
@@ -24,7 +24,7 @@
   The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
 
-    <title>The Six Myths of Erlang Performance</title>
+    <title>The Seven Myths of Erlang Performance</title>
     <prepared>Bjorn Gustavsson</prepared>
     <docno></docno>
     <date>2007-11-10</date>
@@ -175,5 +175,23 @@ vanilla_reverse([], Acc) ->
     <p>That was once true, but from R6B the BEAM compiler can see
     that a variable is not used.</p>
   </section>
+
+  <section>
+    <title>Myth: A NIF Always Speeds Up Your Program</title>
+
+    <p>Rewriting Erlang code to a NIF to make it faster should be
+    seen as a last resort. It is only guaranteed to be dangerous,
+    but not guaranteed to speed up the program.</p>
+
+    <p>Doing too much work in each NIF call will
+    <seealso marker="erts:erl_nif#WARNING">degrade responsiveness
+    of the VM</seealso>. Doing too little work may mean that
+    the gain of the faster processing in the NIF is eaten up by
+    the overhead of calling the NIF and checking the arguments.</p>
+
+    <p>Be sure to read about
+    <seealso marker="erts:erl_nif#lengthy_work">Long-running NIFs</seealso>
+    before writing a NIF.</p>
+  </section>
 </chapter>
 
-- 
cgit v1.2.3