Replace off_heap_message_queue option with message_queue_data option

The message_queue_data option can have the values
 - off_heap
 - on_heap
 - mixed

1 files changed, 60 insertions, 34 deletions

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 2e82bb62a9..6ed03f3dfc 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -59,6 +59,12 @@
     </datatype>
 
     <datatype>
+      <name name="message_queue_data"></name>
+      <desc><p>See <seealso marker="#process_flag_message_queue_data"><c>erlang:process_flag(message_queue_data, MQD)</c></seealso>.</p>
+      </desc>
+    </datatype>
+
+    <datatype>
       <name name="timestamp"></name>
       <desc><p>See <seealso marker="#timestamp/0">erlang:timestamp/0</seealso>.</p>
       </desc>
@@ -4280,39 +4286,52 @@ os_prompt% </pre>
         <p>Returns the old value of the flag.</p>
       </desc>
     </func>
-    <marker id="process_flag_off_heap_message_queue"/>
+    <marker id="process_flag_message_queue_data"/>
     <func>
       <name name="process_flag" arity="2" clause_i="5"/>
-      <fsummary>Set process flag <c>off_heap_message_queue</c> for the calling process</fsummary>
+      <fsummary>Set process flag <c>message_queue_data</c> for the calling process</fsummary>
+      <type name="message_queue_data"/>
       <desc>
 	<p>This flag determines how messages in the message queue
 	are stored. When the flag is:</p>
         <taglist>
-          <tag><c>true</c></tag>
+          <tag><c>off_heap</c></tag>
 	  <item><p>
 	    <em>All</em> messages in the message queue will be stored
 	    outside of the process heap. This implies that <em>no</em>
 	    messages in the message queue will be part of a garbage
 	    collection of the process.
 	  </p></item>
-          <tag><c>false</c></tag>
+          <tag><c>on_heap</c></tag>
+	  <item><p>
+	    All messages in the message queue will eventually be
+	    placed on heap. They may however temporarily be stored
+	    off heap. This is how messages always have been stored
+	    up until ERTS version 8.0.
+	  </p></item>
+          <tag><c>mixed</c></tag>
 	  <item><p>
 	    Messages may be placed either on the heap or outside
 	    of the heap.
 	  </p></item>
         </taglist>
 	<p>
+	  The default <c>message_queue_data</c> process flag is determined
+	  by the <seealso marker="erl#+xmqd"><c>+xmqd</c></seealso>
+	  <c>erl</c> command line argument.
+	</p>
+	<p>
 	  If the process potentially may get a hugh amount of messages,
-	  you are recommended to set the flag to <c>true</c>. This since
-	  a garbage collection with lots of messages placed on the heap
-	  may become extremly expensive. Performance of the actual
-	  message passing is however generally better when setting the
-	  flag to <c>false</c>.
+	  you are recommended to set the flag to <c>off_heap</c>. This
+	  since a garbage collection with lots of messages placed on
+	  the heap may become extremly expensive and the process may
+	  consume large amounts of memory. Performance of the
+	  actual message passing is however generally better when not
+	  using the <c>off_heap</c> flag.
 	</p>
 	<p>
-	  When changing this flag from <c>false</c> to <c>true</c>,
-	  all messages in the message queue are moved off heap. This
-	  work has been initiated but not completed when this function
+	  When changing this flag messages will be moved. This work
+	  has been initiated but not completed when this function
 	  call returns.
 	</p>
         <p>Returns the old value of the flag.</p>
@@ -4478,6 +4497,7 @@ os_prompt% </pre>
       <type name="process_info_result_item"/>
       <type name="priority_level"/>
       <type name="stack_item"/>
+      <type name="message_queue_data" />
       <desc>
         <p>Returns a list containing <c><anno>InfoTuple</anno></c>s with
 	  miscellaneous information about the process identified by
@@ -4530,6 +4550,7 @@ os_prompt% </pre>
       <type name="process_info_result_item"/>
       <type name="stack_item"/>
       <type name="priority_level"/>
+      <type name="message_queue_data" />
       <desc>
         <p>Returns information about the process identified by
            <c><anno>Pid</anno></c>, as specified by
@@ -4698,13 +4719,14 @@ os_prompt% </pre>
               monitor by name, the list item is
               <c>{process, {<anno>RegName</anno>, <anno>Node</anno>}}</c>.</p>
           </item>
-          <tag><c>{off_heap_message_queue, <anno>OHMQ</anno>}</c></tag>
+          <tag><c>{message_queue_data, <anno>MQD</anno>}</c></tag>
           <item>
-            <p>Returns the current state of the <c>off_heap_message_queue</c>
-	    process flag. <c><anno>OHMQ</anno></c> is either <c>true</c>, or
-	    <c>false</c>. For more information, see the documentation of
-            <seealso marker="#process_flag_off_heap_message_queue"><c>process_flag(off_heap_message_queue,
-	    OHMQ)</c></seealso>.</p>
+            <p>Returns the current state of the <c>message_queue_data</c>
+	    process flag. <c><anno>MQD</anno></c> is either <c>off_heap</c>,
+	    <c>on_heap</c>, or <c>mixed</c>. For more information, see the
+	    documentation of
+            <seealso marker="#process_flag_message_queue_data"><c>process_flag(message_queue_data,
+	    MQD)</c></seealso>.</p>
           </item>
           <tag><c>{priority, <anno>Level</anno>}</c></tag>
           <item>
@@ -5474,6 +5496,7 @@ true</pre>
       <name name="spawn_opt" arity="2"/>
       <fsummary>Creates a new process with a fun as entry point.</fsummary>
       <type name="priority_level"/>
+      <type name="message_queue_data" />
       <type name="spawn_opt_option" />
       <desc>
         <p>Returns the process identifier (pid) of a new process
@@ -5490,6 +5513,7 @@ true</pre>
       <name name="spawn_opt" arity="3"/>
       <fsummary>Creates a new process with a fun as entry point on a given node.</fsummary>
       <type name="priority_level"/>
+      <type name="message_queue_data" />
       <type name="spawn_opt_option" />
       <desc>
         <p>Returns the process identifier (pid) of a new process started
@@ -5505,6 +5529,7 @@ true</pre>
       <name name="spawn_opt" arity="4"/>
       <fsummary>Creates a new process with a function as entry point.</fsummary>
       <type name="priority_level"/>
+      <type name="message_queue_data" />
       <type name="spawn_opt_option" />
       <desc>
         <p>Works as
@@ -5607,17 +5632,17 @@ true</pre>
               fine-tuning an application and to measure the execution
               time with various <c><anno>VSize</anno></c> values.</p>
           </item>
-          <tag><c>{off_heap_message_queue, <anno>OHMQ</anno>}</c></tag>
+          <tag><c>{message_queue_data, <anno>MQD</anno>}</c></tag>
           <item>
-            <p>Sets the state of the <c>off_heap_message_queue</c> process
-	    flag. <c><anno>OHMQ</anno></c> should be either <c>true</c>, or
-	    <c>false</c>. The default <c>off_heap_message_queue</c> process
-	    flag is determined by the
-	    <seealso marker="erl#+xohmq"><c>+xohmq</c></seealso> <c>erl</c>
+            <p>Sets the state of the <c>message_queue_data</c> process
+	    flag. <c><anno>MQD</anno></c> should be either <c>off_heap</c>,
+	    <c>on_heap</c>, or <c>mixed</c>. The default
+	    <c>message_queue_data</c> process flag is determined by the
+	    <seealso marker="erl#+xmqd"><c>+xmqd</c></seealso> <c>erl</c>
 	    command line argument. For more information, see the
 	    documentation of
-            <seealso marker="#process_flag_off_heap_message_queue"><c>process_flag(off_heap_message_queue,
-	    <anno>OHMQ</anno>)</c></seealso>.</p>
+            <seealso marker="#process_flag_message_queue_data"><c>process_flag(message_queue_data,
+	    <anno>MQD</anno>)</c></seealso>.</p>
           </item>
         </taglist>
       </desc>
@@ -5627,6 +5652,7 @@ true</pre>
       <name name="spawn_opt" arity="5"/>
       <fsummary>Creates a new process with a function as entry point on a given node.</fsummary>
       <type name="priority_level"/>
+      <type name="message_queue_data" />
       <type name="spawn_opt_option" />
       <desc>
         <p>Returns the process identifier (pid) of a new process started
@@ -7106,15 +7132,15 @@ ok
               used by the runtime system. It is on the form
 	      "&lt;major ver&gt;.&lt;minor ver&gt;".</p>
           </item>
-          <tag><marker id="system_info_off_heap_message_queue"><c>off_heap_message_queue</c></marker></tag>
+          <tag><marker id="system_info_message_queue_data"><c>message_queue_data</c></marker></tag>
           <item>
-            <p>Returns the default value of the <c>off_heap_message_queue</c>
-	    process flag which is either <c>true</c> or <c>false</c>. This
-	    default is set by the <c>erl</c> command line argument
-	    <seealso marker="erl#+xohmq"><c>+xohmq</c></seealso>. For more information on the
-	    <c>off_heap_message_queue</c> process flag, see documentation of
-            <seealso marker="#process_flag_off_heap_message_queue"><c>process_flag(off_heap_message_queue,
-	    OHMQ)</c></seealso>.</p>
+            <p>Returns the default value of the <c>message_queue_data</c>
+	    process flag which is either <c>off_heap</c>, <c>on_heap</c>, or <c>mixed</c>.
+	    This default is set by the <c>erl</c> command line argument
+	    <seealso marker="erl#+xmqd"><c>+xmqd</c></seealso>. For more information on the
+	    <c>message_queue_data</c> process flag, see documentation of
+            <seealso marker="#process_flag_message_queue_data"><c>process_flag(message_queue_data,
+	    MQD)</c></seealso>.</p>
           </item>
           <tag><marker id="system_info_otp_release"><c>otp_release</c></marker></tag>
           <item>