# HG changeset patch
# User Armin Rigo <arigo@tunes.org>
# Date 1468492648 -7200
#      Thu Jul 14 12:37:28 2016 +0200
# Branch extradoc
# Node ID c4d464e272a95ef7c84925a2834db1ab8adecfa1
# Parent  b1d29a113eecd1e2239c2e30f18e4bab6ad80b9d
Document the memory usage behavior of PyPy, because it is not very clear
that memory usage *does* go down in systems with MADV_FREE.

diff --git a/compat.html b/compat.html
--- a/compat.html
+++ b/compat.html
@@ -124,6 +124,15 @@
 as on CPython: they run &ldquo;some time later&rdquo; in PyPy (or not at all if
 the program finishes running in the meantime).  See <a class="reference external" href="http://pypy.readthedocs.org/en/latest/cpython_differences.html#differences-related-to-garbage-collection-strategies">more details
 here</a>.</p>
+<p>Note that PyPy returns unused memory to the operating system if there
+is a madvise() system call (at least Linux, OS/X, BSD).  It is
+important to realize that you may not see this in <tt class="docutils literal">top</tt>.  The unused
+pages are marked with <tt class="docutils literal">MADV_FREE</tt>, which tells the system &ldquo;if you
+need more memory at some point, grab this page&rdquo;.  As long as memory is
+plentiful, the <tt class="docutils literal">RES</tt> column in <tt class="docutils literal">top</tt> remains high.  (Exceptions to
+this rule are systems with no <tt class="docutils literal">MADV_FREE</tt>, where we use
+<tt class="docutils literal">MADV_DONTNEED</tt>, which forcefully lowers the <tt class="docutils literal">RES</tt>.  This includes
+Linux &lt;= 4.4.)</p>
 <p>A more complete list of known differences is available at <a class="reference external" href="http://pypy.readthedocs.org/en/latest/cpython_differences.html">our dev site</a>.</p>
 </div>
 <div id="sidebar">
diff --git a/source/compat.txt b/source/compat.txt
--- a/source/compat.txt
+++ b/source/compat.txt
@@ -114,6 +114,16 @@
 the program finishes running in the meantime).  See `more details
 here`_.
 
+Note that PyPy returns unused memory to the operating system if there
+is a madvise() system call (at least Linux, OS/X, BSD).  It is
+important to realize that you may not see this in ``top``.  The unused
+pages are marked with ``MADV_FREE``, which tells the system "if you
+need more memory at some point, grab this page".  As long as memory is
+plentiful, the ``RES`` column in ``top`` remains high.  (Exceptions to
+this rule are systems with no ``MADV_FREE``, where we use
+``MADV_DONTNEED``, which forcefully lowers the ``RES``.  This includes
+Linux <= 4.4.)
+
 A more complete list of known differences is available at `our dev site`_.
 
 .. _`CPython C API`: http://docs.python.org/c-api/