diff options
Diffstat (limited to 'erts/doc')
| -rw-r--r-- | erts/doc/src/erl.xml | 17 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 39 |
2 files changed, 46 insertions, 10 deletions
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 7b90a1ccca..37387f2c59 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,14 @@ 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. 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..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> @@ -1702,7 +1723,7 @@ enif_map_iterator_destroy(env, &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> |