Minor reorganization of dirty NIF documentation

1 files changed, 29 insertions, 26 deletions

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index c9b2092c17..f3921f1922 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -385,18 +385,39 @@ ok
 	    <p>
 	      A NIF that cannot be split and cannot execute in a millisecond or
 	      less is called a "dirty NIF" because it performs work that the
-	      Erlang runtime cannot handle cleanly. Applications that make use
-	      of such functions must indicate to the runtime that the functions
-	      are dirty so they can be handled specially. To schedule a dirty
-	      NIF for execution, the appropriate flags value can be set for the
-	      NIF in its <seealso marker="#ErlNifFunc"><c>ErlNifFunc</c></seealso>
+	      ordinary schedulers of the Erlang runtime system cannot handle cleanly.
+	      Applications that make use of such functions must indicate to the
+	      runtime that the functions are dirty so they can be handled
+	      specially. This is handled by executing dirty jobs on a separate
+	      set of schedulers called dirty schedulers. A dirty NIF executing
+	      on a dirty scheduler does not have the same duration restriction
+	      as a normal NIF.
+	    </p>
+
+	    <p>
+	      It is important to classify the dirty job correct. An I/O bound
+	      job should be classified as such, and a CPU bound job should be
+	      classified as such. If you should classify CPU bound jobs
+	      as I/O bound jobs, dirty I/O schedulers might starve ordinary
+	      schedulers. I/O bound jobs are expected to either block waiting
+	      for I/O, and/or spend a limited amount of time moving data.
+	    </p>
+
+	    <p>
+	      To schedule a dirty NIF for execution, the appropriate
+	      <c>flags</c> value can be set for the NIF in its
+	      <seealso marker="#ErlNifFunc"><c>ErlNifFunc</c></seealso>
 	      entry, or the application can call
 	      <seealso marker="#enif_schedule_nif"><c>enif_schedule_nif</c></seealso>,
 	      passing to it a pointer to the dirty NIF to be executed and
 	      indicating with the <c>flags</c> argument whether it expects the
-	      operation to be CPU-bound or I/O-bound. A dirty NIF executing
-	      on a dirty scheduler does not have the same duration restriction
-	      as a normal NIF.
+	      operation to be CPU-bound or I/O-bound. 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 executes on
+	      the correct type of dirty scheduler at all times. 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>.
 	    </p>
 
 	    <p>
@@ -442,24 +463,6 @@ 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>