From c9ad0c9fed1d33891f5fa8a4c4511de48417ec10 Mon Sep 17 00:00:00 2001 From: Rickard Green 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(-) 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 like the amount of dirty CPU schedulers. 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.

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

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 ErlNifFunc + 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. +

+ +

+ 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. +

+ +

+ To schedule a dirty NIF for execution, the appropriate + flags value can be set for the NIF in its + ErlNifFunc entry, or the application can call enif_schedule_nif, passing to it a pointer to the dirty NIF to be executed and indicating with the flags 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 enif_schedule_nif so that it executes on + the correct type of dirty scheduler at all times. For more + information see the documentation of the erl command line + arguments +SDcpu, + and +SDio.

@@ -442,24 +463,6 @@ ok dirty NIF has completed.

-

- 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 erl command line arguments - +SDcpu, and - +SDio as well - as enif_schedule_nif, - and ErlNifFunc. - A job that alternates between I/O bound and CPU bound can - be reclassified and rescheduled using enif_schedule_nif - so that it exectutes on the correct type of dirty scheduler - at all times. -

-

Currently known issues that are planned to be fixed:

-- cgit v1.2.3