From c1eebebee04d7a9585d47583f15bf56b25e96a17 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Fri, 16 Dec 2016 20:03:28 +0100 Subject: erts: Add some improvements to erl_nif docs --- erts/doc/src/erl_nif.xml | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 906c1be17b..185ecd9ed9 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -123,7 +123,7 @@ ok "Hello world!"

A better solution for a real module is to take advantage of the new - directive on load (see section + directive on_load (see section Running a Function When a Module is Loaded in the Erlang Reference Manual) to load the NIF library automatically when the module is @@ -135,27 +135,14 @@ ok away by the compiler, causing loading of the NIF library to fail.

-

A loaded NIF library is tied to the Erlang module code version - that loaded it. If the module is upgraded with a new version, the - new Erlang code need to load its own NIF library (or maybe choose not - to). The new code version can, however, choose to load the - same NIF library as the old code if it wants to. Sharing the - dynamic library means that static data defined by the library - is shared as well. To avoid unintentionally shared static - data, each Erlang module code can keep its own private data. This - private data can be set when the NIF library is loaded and - then retrieved by calling - enif_priv_data.

- -

A NIF library cannot be loaded explicitly. A library is - automatically unloaded when the module code that it belongs to is purged - by the code server.

+

Once loaded, a NIF library is persistent. It will not be unloaded + until the module code version that it belongs to is purged.

Functionality -

All functions that a NIF library needs to do with Erlang are - performed through the NIF API functions. Functions exist +

All interaction between NIF code and the Erlang runtime system is + performed by calling NIF API functions. Functions exist for the following functionality:

@@ -286,6 +273,19 @@ return term; library is postponed as long as there exist resource objects with a destructor function in the library.

+ Module upgrade and static data + +

A loaded NIF library is tied to the Erlang module instance + that loaded it. If the module is upgraded, the new module instance + needs to load its own NIF library (or maybe choose not to). The new + module instance can, however, choose to load the exact same NIF library + as the old code if it wants to. Sharing the dynamic library means that + static data defined by the library is shared as well. To avoid + unintentionally shared static data between module instances, each Erlang + module version can keep its own private data. This private data can be + set when the NIF library is loaded and later retrieved by calling + enif_priv_data.

+ Threads and concurrency

A NIF is thread-safe without any explicit synchronization as @@ -525,7 +525,7 @@ return term;

load is called when the NIF library is loaded and no previously loaded library exists for this module.

*priv_data can be set to point to some private data - that the library needs to keep a state between NIF + if the library needs to keep a state between NIF calls. enif_priv_data returns this pointer. *priv_data is initialized to NULL when load is called.

-- cgit v1.2.3 From 0d20adbfbb0918c8d6bfc629e9e4ff89d2ef1a64 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Thu, 12 Jan 2017 14:55:53 +0100 Subject: Remove experimental disclaimer on dirty schedulers --- erts/doc/src/erl_nif.xml | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 185ecd9ed9..51b095e6ef 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -402,14 +402,14 @@ return term; Dirty NIF -

The dirty NIF functionality described here - is experimental. Dirty NIF support is available only when - the emulator is configured with dirty schedulers enabled. This - feature is disabled by default. The Erlang runtime - without SMP support does not support dirty schedulers even when - the dirty scheduler support is enabled. To check at runtime for - the presence of dirty scheduler threads, code can use the - +

Dirty NIF support is available only when the emulator is + configured with dirty scheduler support. As of ERTS version + 9.0, dirty scheduler support is enabled by default on the + runtime system with SMP support. The Erlang runtime without + SMP support does not support dirty schedulers even + when the dirty scheduler support is explicitly enabled. To + check at runtime for the presence of dirty scheduler threads, + code can use the enif_system_info() API function.

A NIF that cannot be split and cannot execute in a millisecond @@ -642,9 +642,6 @@ typedef struct {

flags can be used to indicate that the NIF is a dirty NIF that is to be executed on a dirty scheduler thread.

-

The dirty NIF functionality described here is - experimental. You have to enable support for dirty - schedulers when building OTP to try out the functionality.

If the dirty NIF is expected to be CPU-bound, its flags field is to be set to ERL_NIF_DIRTY_JOB_CPU_BOUND or ERL_NIF_DIRTY_JOB_IO_BOUND.

@@ -2450,9 +2447,6 @@ enif_map_iterator_destroy(env, &iter); application to break up long-running work into multiple regular NIF calls or to schedule a dirty NIF to execute on a dirty scheduler thread.

-

The dirty NIF functionality described here is - experimental. You have to enable support for dirty - schedulers when building OTP to try out the functionality.

fun_name @@ -2463,7 +2457,7 @@ enif_map_iterator_destroy(env, &iter); flags

Must be set to 0 for a regular NIF. If the emulator was - built with the experimental dirty scheduler support enabled, + built with dirty scheduler support enabled, flags can be set to either ERL_NIF_DIRTY_JOB_CPU_BOUND if the job is expected to be CPU-bound, or ERL_NIF_DIRTY_JOB_IO_BOUND for -- cgit v1.2.3