aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erl.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erl.xml')
-rw-r--r--erts/doc/src/erl.xml177
1 files changed, 112 insertions, 65 deletions
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index 02082e57c6..cfbc38f176 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -41,25 +41,11 @@
to scroll back to text which has scrolled off the screen.
The <c><![CDATA[erl]]></c> program must be used, however, in pipelines or if
you want to redirect standard input or output.</p>
- <note><p>As of ERTS version 5.8 (OTP-R14A) the runtime system will by
- default bind schedulers to logical processors using the
- <c>default_bind</c> bind type if the amount of schedulers are
- at least equal to the amount of logical processors configured,
- binding of schedulers is supported, and a CPU topology is
- available at startup.
- </p><p>
- If the Erlang runtime system is the only operating system
- process that binds threads to logical processors, this
- improves the performance of the runtime system. However,
- if other operating system processes (as for example
- another Erlang runtime system) also bind threads to
- logical processors, there might be a performance penalty
- instead. If this is the case you, are are advised to
- unbind the schedulers using the
- <seealso marker="#+sbt">+sbtu</seealso> command line argument,
- or by invoking
- <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type,
- unbound)</seealso>.</p>
+ <note><p>As of ERTS version 5.9 (OTP-R15B) the runtime system will by
+ default <em>not</em> bind schedulers to logical processors.
+ For more information see documentation of the
+ <seealso marker="#+sbt">+sbt</seealso> system flag.
+ </p>
</note>
</description>
<funcs>
@@ -587,6 +573,13 @@
<p>Enables auto load tracing, displaying info while loading
code.</p>
</item>
+ <tag><c><![CDATA[+L]]></c></tag>
+ <item>
+ <p>Don't load information about source filenames and line numbers.
+ This will save some memory, but exceptions will not contain
+ information about the filenames and line numbers.
+ </p>
+ </item>
<tag><marker id="erts_alloc"><c><![CDATA[+MFlag Value]]></c></marker></tag>
<item>
<p>Memory allocator specific flags, see
@@ -672,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. Intel's 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>
@@ -718,24 +736,47 @@
that the <c>+sct</c> flag may have to be passed before the
<c>+sbt</c> flag on the command line (in case no CPU topology
has been automatically detected).</p>
- <p>The runtime system will by default bind schedulers to logical
- processors using the <c>default_bind</c> bind type if the amount
- of schedulers are at least equal to the amount of logical
- processors configured, binding of schedulers is supported,
- and a CPU topology is available at startup.
+ <p>The runtime system will by default <em>not</em> bind schedulers
+ to logical processors.
</p>
- <p><em>NOTE:</em> If the Erlang runtime system is the only operating
- system process that binds threads to logical processors, this
- improves the performance of the runtime system. However, if other
- operating system processes (as for example another Erlang runtime
- system) also bind threads to logical processors, there might be a
- performance penalty instead. If this is the case you, are advised
- to unbind the schedulers using the <c>+sbtu</c> command line
- argument, or by invoking
- <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type,
- unbound)</seealso>.</p>
- <p>For more information, see
- <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, SchedulerBindType)</seealso>.
+ <p><em>NOTE:</em> If the Erlang runtime system is the only operating system
+ process that binds threads to logical processors, this
+ improves the performance of the runtime system. However,
+ if other operating system processes (as for example
+ another Erlang runtime system) also bind threads to
+ logical processors, there might be a performance penalty
+ 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>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>
+ <item>
+ <p>Enable or disable scheduler compaction of load. By default
+ scheduler compaction of load is enabled. When enabled, load
+ balancing will strive for a load distribution which causes
+ as many scheduler threads as possible to be fully loaded (i.e.,
+ not run out of work). This is accomplished by migrating load
+ (e.g. runnable processes) into a smaller set of schedulers
+ when schedulers frequently run out of work. When disabled,
+ the frequency with which schedulers run out of work will
+ not be taken into account by the load balancing logic.
</p>
</item>
<tag><marker id="+sct"><c>+sct CpuTopology</c></marker></tag>
@@ -753,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 topology. 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
@@ -852,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>
@@ -987,7 +1034,7 @@
the <c><![CDATA[-extra]]></c> section, i.e. the end of the command line
following after an <c><![CDATA[-extra]]></c> flag.</p>
</item>
- <tag><c><![CDATA[ERL_ZFLAGS]]></c>and <c><![CDATA[ERL_FLAGS]]></c></tag>
+ <tag><c><![CDATA[ERL_ZFLAGS]]></c> and <c><![CDATA[ERL_FLAGS]]></c></tag>
<item>
<p>The content of these environment variables will be added to the
end of the command line for <c><![CDATA[erl]]></c>.</p>