Merge branch 'egil/binary-gc' into ccase/r13b04_dev

* egil/binary-gc:
  Add documentation for binary heap size settings.
  Add tracing capabilities for binary virtual heap
  Add min heap size start options to beam and erl
  Improve binary garbage collection

OTP-8370  The default settings for garbage collection of binaries has been
          adjusted to be less aggressive than in R13B03. It is now also
          possible configure the settings for binary GC. See the
          documentation for spawn_opt/2-5, erlang:system_info/1,
          erlang:system_flag/2, process_flag/2-3, erlang:trace/3, and the
          documenation for erl for the new command line options +hms and
          +hmbs.

2 files changed, 81 insertions, 8 deletions

diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index 90a3c53a37..6f5dd248ce 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -4,7 +4,7 @@
 <comref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>erl</title>
@@ -527,11 +527,16 @@
 	<p>Calling <c>erlang:halt/1</c> with a string argument will still
 	produce a crash dump.</p>
       </item>
-      <tag><c><![CDATA[+h Size]]></c></tag>
+      <tag><c><![CDATA[+hms Size]]></c></tag>
       <item>
         <p>Sets the default heap size of processes to the size
           <c><![CDATA[Size]]></c>.</p>
       </item>
+      <tag><c><![CDATA[+hmbs Size]]></c></tag>
+      <item>
+        <p>Sets the default binary virtual heap size of processes to the size
+          <c><![CDATA[Size]]></c>.</p>
+      </item>
       <tag><c><![CDATA[+K true | false]]></c></tag>
       <item>
         <p>Enables or disables the kernel poll functionality if
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 4a401156d1..28b040a441 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -3469,6 +3469,11 @@ os_prompt%</pre>
             <p>This changes the minimum heap size for the calling
               process.</p>
           </item>
+          <tag><c>process_flag(min_bin_vheap_size, MinBinVHeapSize)</c></tag>
+          <item>
+            <p>This changes the minimum binary virtual heap size for the calling
+              process.</p>
+          </item>
           <tag><c>process_flag(priority, Level)</c></tag>
           <item>
             <marker id="process_flag_priority"></marker>
@@ -3800,6 +3805,14 @@ os_prompt%</pre>
             <p><c>MessageQueue</c> is a list of the messages to
               the process, which have not yet been processed.</p>
           </item>
+          <tag><c>{min_heap_size, MinHeapSize}</c></tag>
+          <item>
+            <p><c>MinHeapSize</c> is the minimum heap size for the process.</p>
+          </item>
+          <tag><c>{min_bin_vheap_size, MinBinVHeapSize}</c></tag>
+          <item>
+            <p><c>MinBinVHeapSize</c> is the minimum binary virtual heap size for the process.</p>
+          </item>
           <tag><c>{monitored_by, Pids}</c></tag>
           <item>
             <p>A list of pids that are monitoring the process (with
@@ -4533,10 +4546,11 @@ true</pre>
       <fsummary>Create a new process with a fun as entry point</fsummary>
       <type>
         <v>Fun = fun()</v>
-        <v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
+        <v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
         <v>&nbsp;Level = low | normal | high</v>
         <v>&nbsp;Number = int()</v>
         <v>&nbsp;Size = int()</v>
+        <v>&nbsp;VSize = int()</v>
       </type>
       <desc>
         <p>Returns the pid of a new process started by the application
@@ -4554,10 +4568,11 @@ true</pre>
       <type>
         <v>Node = node()</v>
         <v>Fun = fun()</v>
-        <v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
+        <v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
         <v>&nbsp;Level = low | normal | high</v>
         <v>&nbsp;Number = int()</v>
         <v>&nbsp;Size = int()</v>
+        <v>&nbsp;VSize = int()</v>
       </type>
       <desc>
         <p>Returns the pid of a new process started by the application
@@ -4573,10 +4588,11 @@ true</pre>
       <type>
         <v>Module = Function = atom()</v>
         <v>Args = [term()]</v>
-        <v>Option = link | monitor | {priority, Level}  | {fullsweep_after, Number} | {min_heap_size, Size}</v>
+        <v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
         <v>&nbsp;Level = low | normal | high</v>
         <v>&nbsp;Number = int()</v>
         <v>&nbsp;Size = int()</v>
+        <v>&nbsp;VSize = int()</v>
       </type>
       <desc>
         <p>Works exactly like
@@ -4656,6 +4672,23 @@ true</pre>
               fine-tuning an application and to measure the execution
               time with various <c>Size</c> values.</p>
           </item>
+          <tag><c>{min_bin_vheap_size, VSize}</c></tag>
+          <item>
+            <p>This option is only useful for performance tuning.
+              In general, you should not use this option unless you
+              know that there is problem with execution times and/or
+              memory consumption, and you should measure to make sure
+              that the option improved matters.
+              </p>
+	      <p>Gives a minimum binary virtual heap size in words. Setting this value
+              higher than the system default might speed up some
+              processes because less garbage collection is done.
+              Setting too high value, however, might waste memory.
+              Therefore, it is recommended to use this option only for
+              fine-tuning an application and to measure the execution
+              time with various <c>VSize</c> values.</p>
+          </item>
+
         </taglist>
       </desc>
     </func>
@@ -4666,10 +4699,11 @@ true</pre>
         <v>Node = node()</v>
         <v>Module = Function = atom()</v>
         <v>Args = [term()]</v>
-        <v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
+        <v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
         <v>&nbsp;Level = low | normal | high</v>
         <v>&nbsp;Number = int()</v>
         <v>&nbsp;Size = int()</v>
+        <v>&nbsp;VSize = int()</v>
       </type>
       <desc>
         <p>Returns the pid of a new process started by the application
@@ -5002,6 +5036,17 @@ true</pre>
               <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or
               <seealso marker="#process_flag/2">process_flag/2</seealso>. </p>
           </item>
+          <tag><c>erlang:system_flag(min_bin_vheap_size, MinBinVHeapSize)</c></tag>
+          <item>
+            <p>Sets the default minimum binary virtual heap size for processes. The
+              size is given in words. The new <c>min_bin_vhheap_size</c> only
+              effects processes spawned after the change of
+              <c>min_bin_vhheap_size</c> has been made.
+              The <c>min_bin_vheap_size</c> can be set for individual
+              processes by use of
+              <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or
+              <seealso marker="#process_flag/2">process_flag/2</seealso>. </p>
+          </item>
           <tag><c>erlang:system_flag(multi_scheduling, BlockState)</c></tag>
           <item>
             <marker id="system_flag_multi_scheduling"></marker>
@@ -5613,6 +5658,16 @@ true</pre>
           <item>
             <p>Returns a string containing the Erlang machine name.</p>
           </item>
+	  <tag><c>min_heap_size</c></tag>
+          <item>
+	      <p>Returns <c>{min_heap_size, MinHeapSize}</c> where <c>MinHeapSize</c> is the current system wide
+	      minimum heap size for spawned processes.</p>
+          </item>
+	  <tag><c>min_bin_vheap_size</c></tag>
+          <item>
+	      <p>Returns <c>{min_bin_vheap_size, MinBinVHeapSize}</c> where <c>MinBinVHeapSize</c> is the current system wide
+	      minimum binary virtual heap size for spawned processes.</p>
+          </item>
           <tag><c>modified_timing_level</c></tag>
           <item>
             <p>Returns the modified timing level (an integer) if
@@ -6449,6 +6504,19 @@ true</pre>
               <tag><c>mbuf_size</c></tag>
               <item>The combined size of message buffers associated with
                the process.</item>
+
+              <tag><c>bin_vheap_size</c></tag>
+              <item>The total size  of unique off-heap binaries referenced from the process heap.</item>
+              <tag><c>bin_vheap_block_size</c></tag>
+	      <item>The total size of binaries, in words, allowed in the virtual
+	       heap in the process before doing a garbage collection. </item>
+              <tag><c>bin_old_vheap_size</c></tag>
+              <item>The total size of unique off-heap binaries referenced from the process old heap.</item>
+              <tag><c>bin_vheap_block_size</c></tag>
+	      <item>The total size of binaries, in words, allowed in the virtual
+	       old heap in the process before doing a garbage collection. </item>
+
+
             </taglist>
             <p>All sizes are in words.</p>
           </item>