aboutsummaryrefslogtreecommitdiffstats
path: root/erts
diff options
context:
space:
mode:
authorRickard Green <[email protected]>2016-06-16 17:35:21 +0200
committerRickard Green <[email protected]>2016-06-16 17:35:21 +0200
commit7c349de647fa1e56960201a72cc6c0d863137cd8 (patch)
tree12cd32f72e270aead4a6d1d2896ff7f2fcf9b806 /erts
parent06052cba84436becbef02a571d15c55e2ffdab31 (diff)
parent615b79a01706033e1ef0d78f020ebbb47fc80b86 (diff)
downloadotp-7c349de647fa1e56960201a72cc6c0d863137cd8.tar.gz
otp-7c349de647fa1e56960201a72cc6c0d863137cd8.tar.bz2
otp-7c349de647fa1e56960201a72cc6c0d863137cd8.zip
Merge branch 'rickard/ds-job-type-doc'
* rickard/ds-job-type-doc: Add documentation about dirty job type
Diffstat (limited to 'erts')
-rw-r--r--erts/doc/src/erl.xml19
-rw-r--r--erts/doc/src/erl_nif.xml20
2 files changed, 37 insertions, 2 deletions
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index 7b90a1ccca..436c2c57e1 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -915,6 +915,13 @@
number of dirty CPU schedulers online can be changed at run time via
<seealso marker="erlang#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>.
</p>
+ <p>
+ The amount of dirty CPU schedulers is limited by the amount of
+ normal schedulers in order to limit the effect on processes
+ executing on ordinary schedulers. If the amount of dirty CPU
+ schedulers was allowed to be unlimited, dirty CPU bound jobs would
+ potentially starve normal jobs.
+ </p>
<p>This option is ignored if the emulator doesn't have threading support
enabled. Currently, <em>this option is experimental</em> and is supported only
if the emulator was configured and built with support for dirty schedulers
@@ -944,7 +951,7 @@
enabled (it's disabled by default).
</p>
</item>
- <tag><marker id="+SDio"/><c><![CDATA[+SDio IOSchedulers]]></c></tag>
+ <tag><marker id="+SDio"/><c><![CDATA[+SDio DirtyIOSchedulers]]></c></tag>
<item>
<p>Sets the number of dirty I/O scheduler threads to create when threading
support has been enabled. The valid range is 0-1024. By default, the number
@@ -952,6 +959,16 @@
threads in the <seealso marker="#async_thread_pool_size">async thread pool
</seealso>.
</p>
+ <p>
+ The amount of dirty IO schedulers is not limited by the amount of
+ normal schedulers <seealso marker="#+SDcpu">like the amount of
+ dirty CPU schedulers</seealso>. This since only I/O bound work is
+ expected to execute on dirty I/O schedulers. I/O bound jobs are
+ expected to either block waiting for I/O, and/or spend a limited
+ amount of time moving data. However, if the user should schedule CPU
+ bound jobs on dirty I/O schedulers, these jobs might starve ordinary
+ jobs executing on ordinary schedulers.
+ </p>
<p>This option is ignored if the emulator doesn't have threading support
enabled. Currently, <em>this option is experimental</em> and is supported only
if the emulator was configured and built with support for dirty schedulers
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 8b02b3bae1..c9b2092c17 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -442,6 +442,24 @@ ok
dirty NIF has completed.
</p>
+ <p>
+ It is important to classify the dirty job correct. An I/O bound
+ job should be classified as such and execute on a dirty I/O
+ scheduler, and a CPU bound job should be classified as such and
+ execute on a dirty CPU scheduler. If you classify CPU bound jobs
+ as I/O bound jobs, dirty I/O schedulers might starve ordinary
+ schedulers. For more information see the documentation
+ of the <c>erl</c> command line arguments
+ <seealso marker="erl#+SDcpu"><c>+SDcpu</c></seealso>, and
+ <seealso marker="erl#+SDio"><c>+SDio</c></seealso> as well
+ as <seealso marker="#enif_schedule_nif"><c>enif_schedule_nif</c></seealso>,
+ and <seealso marker="#ErlNifFunc"><c>ErlNifFunc</c></seealso>.
+ A job that alternates between I/O bound and CPU bound can
+ be reclassified and rescheduled using <c>enif_schedule_nif</c>
+ so that it exectutes on the correct type of dirty scheduler
+ at all times.
+ </p>
+
<p>Currently known issues that are planned to be fixed:</p>
<list>
<item>
@@ -1702,7 +1720,7 @@ enif_map_iterator_destroy(env, &amp;iter);
be converted to an atom, <c>enif_schedule_nif</c> returns a <c>badarg</c> exception.</p>
<p>The <c>flags</c> argument must be set to 0 for a regular NIF, or if the emulator was built the
experimental dirty scheduler support enabled, <c>flags</c> can be set to either <c>ERL_NIF_DIRTY_JOB_CPU_BOUND</c>
- if the job is expected to be primarily CPU-bound, or <c>ERL_NIF_DIRTY_JOB_IO_BOUND</c> for jobs that will
+ if the job is expected to be CPU-bound, or <c>ERL_NIF_DIRTY_JOB_IO_BOUND</c> for jobs that will
be I/O-bound. If dirty scheduler threads are not available in the emulator, a try to schedule such a job
will result in a <c>badarg</c> exception.</p>