diff options
Diffstat (limited to 'erts/doc/src/erl_nif.xml')
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 55 |
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> |