Add documentation about dirty job type

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>