Merge branch 'rickard/deprecate-runtime-binding/OTP-9749'

* rickard/deprecate-runtime-binding/OTP-9749:
  Deprecate erlang:system_flag/2 arguments scheduler_bind_type and cpu_topology

1 files changed, 75 insertions, 30 deletions

diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index 53f46d2a2e..9fb718e60f 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -665,41 +665,66 @@
 	    </p>
 	    <taglist>
 	      <tag><c>u</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, unbound)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>unbound</c> - Schedulers will not be bound to logical
+		processors, i.e., the operating system decides where the
+		scheduler threads execute, and when to migrate them. This is
+		the default.</p>
+              </item>
 	      <tag><c>ns</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, no_spread)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>no_spread</c> - Schedulers with close scheduler
+		identifiers will be bound as close as possible in hardware.</p>
+              </item>
 	      <tag><c>ts</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, thread_spread)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>thread_spread</c> - Thread refers to hardware threads
+		(e.g. Intels hyper-threads). Schedulers with low scheduler
+		identifiers, will be bound to the first hardware thread of
+		each core, then schedulers with higher scheduler identifiers
+		will be bound to the second hardware thread of each core,
+		etc.</p>
+              </item>
 	      <tag><c>ps</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, processor_spread)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>processor_spread</c> - Schedulers will be spread like
+		<c>thread_spread</c>, but also over physical processor chips.</p>
+              </item>
 	      <tag><c>s</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, spread)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>spread</c> - Schedulers will be spread as much as
+		possible.</p>
+              </item>
 	      <tag><c>nnts</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, no_node_thread_spread)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>no_node_thread_spread</c> - Like <c>thread_spread</c>,
+		but if multiple NUMA (Non-Uniform Memory Access) nodes exists,
+		schedulers will be spread over one NUMA node at a time,
+		i.e., all logical processors of one NUMA node will be bound
+		to schedulers in sequence.</p>
+              </item>
 	      <tag><c>nnps</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, no_node_processor_spread)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>no_node_processor_spread</c> - Like
+		<c>processor_spread</c>, but if multiple NUMA nodes exists,
+		schedulers will be spread over one NUMA node at a time, i.e.,
+		all logical processors of one NUMA node will be bound to
+		schedulers in sequence.</p>
+              </item>
 	      <tag><c>tnnps</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, thread_no_node_processor_spread)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>thread_no_node_processor_spread</c> - A combination of
+		<c>thread_spread</c>, and <c>no_node_processor_spread</c>.
+		Schedulers will be spread over hardware threads across NUMA
+		nodes, but schedulers will only be spread over processors
+		internally in one NUMA node at a time.</p>
+              </item>
 	      <tag><c>db</c></tag>
-	      <item><p>Same as
-	      <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, default_bind)</seealso>.
-	      </p></item>
+              <item>
+                <p><c>default_bind</c> - Binds schedulers the default way.
+		Currently the default is <c>thread_no_node_processor_spread</c>
+		(which might change in the future).</p>
+              </item>
 	    </taglist>
 	    <p>Binding of schedulers is currently only supported on newer
 	       Linux, Solaris, FreeBSD, and Windows systems.</p>
@@ -723,8 +748,22 @@
 	       instead. In some cases this performance penalty might be
 	       severe. If this is the case, you are advised to not
 	       bind the schedulers.</p>
-	    <p>For more information, see
-	    <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, SchedulerBindType)</seealso>.
+            <p>How schedulers are bound matters. For example, in
+	       situations when there are fewer running processes than
+	       schedulers online, the runtime system tries to migrate
+	       processes to schedulers with low scheduler identifiers.
+	       The more the schedulers are spread over the hardware,
+	       the more resources will be available to the runtime
+	       system in such situations.
+	    </p>
+	    <p>
+	       <em>NOTE:</em> If a scheduler fails to bind, this
+	       will often be silently ignored. This since it isn't always
+	       possible to verify valid logical processor identifiers. If
+	       an error is reported, it will be reported to the
+	       <c>error_logger</c>. If you want to verify that the
+	       schedulers actually have bound as requested, call
+	       <seealso marker="erlang#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
 	    </p>
           </item>
           <tag><marker id="+scl"><c>+scl true|false</c></marker></tag>
@@ -755,6 +794,12 @@
               <item><c><![CDATA[<IdDefs> = <LogicalIds><ThreadIds><CoreIds><ProcessorIds><NodeIds> | <LogicalIds><ThreadIds><CoreIds><NodeIds><ProcessorIds>]]></c></item>
               <item><c><![CDATA[CpuTopology = <IdDefs>:<IdDefs> | <IdDefs>]]></c></item>
             </list>
+            <p>Set a user defined CPU topolgy. The user defined
+	       CPU topology will override any automatically detected
+	       CPU topology. The CPU topology is used when
+	       <seealso marker="#+sbt">binding schedulers to logical
+	       processors</seealso>.
+	    </p>
             <p>Upper-case letters signify real identifiers and lower-case
 	       letters signify fake identifiers only used for description
 	       of the topology. Identifiers passed as real identifiers may
@@ -854,7 +899,7 @@
 	        how the real CPU topology looks like is likely to
 		decrease the performance of the runtime system.</p>
 	    <p>For more information, see
-	    <seealso marker="erlang#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.</p>
+	    <seealso marker="erlang#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>.</p>
           </item>
 	  <tag><marker id="+swt"><c>+swt very_low|low|medium|high|very_high</c></marker></tag>
 	  <item>