From c9ad0c9fed1d33891f5fa8a4c4511de48417ec10 Mon Sep 17 00:00:00 2001 From: Rickard Green <rickard@erlang.org> Date: Fri, 17 Jun 2016 11:53:29 +0200 Subject: Minor reorganization of dirty NIF documentation --- erts/doc/src/erl.xml | 4 +--- erts/doc/src/erl_nif.xml | 55 +++++++++++++++++++++++++----------------------- 2 files changed, 30 insertions(+), 29 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 436c2c57e1..37387f2c59 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -963,9 +963,7 @@ 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 + expected to execute on dirty I/O schedulers. If the user should schedule CPU bound jobs on dirty I/O schedulers, these jobs might starve ordinary jobs executing on ordinary schedulers. </p> 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> -- cgit v1.2.3