aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erl_nif.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erl_nif.xml')
-rw-r--r--erts/doc/src/erl_nif.xml62
1 files changed, 28 insertions, 34 deletions
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 13b72863f3..8cdfc80879 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -123,7 +123,7 @@ ok
"Hello world!"</code>
<p>A better solution for a real module is to take advantage of the new
- directive <c>on load</c> (see section
+ directive <c>on_load</c> (see section
<seealso marker="doc/reference_manual:code_loading#on_load">Running a
Function When a Module is Loaded</seealso> 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.</p>
</note>
- <p>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 <seealso marker="#enif_priv_data">
- <c>enif_priv_data</c></seealso>.</p>
-
- <p>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.</p>
+ <p>Once loaded, a NIF library is persistent. It will not be unloaded
+ until the module code version that it belongs to is purged.</p>
</description>
<section>
<title>Functionality</title>
- <p>All functions that a NIF library needs to do with Erlang are
- performed through the NIF API functions. Functions exist
+ <p>All interaction between NIF code and the Erlang runtime system is
+ performed by calling NIF API functions. Functions exist
for the following functionality:</p>
<taglist>
@@ -286,6 +273,19 @@ return term;</code>
library is postponed as long as there exist resource objects with a
destructor function in the library.</p>
</item>
+ <tag>Module upgrade and static data</tag>
+ <item>
+ <p>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
+ <seealso marker="#enif_priv_data"><c>enif_priv_data</c></seealso>.</p>
+ </item>
<tag>Threads and concurrency</tag>
<item>
<p>A NIF is thread-safe without any explicit synchronization as
@@ -402,14 +402,14 @@ return term;</code>
<tag><marker id="dirty_nifs"/>Dirty NIF</tag>
<item>
<note>
- <p><em>The dirty NIF functionality described here
- is experimental</em>. 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
- <seealso marker="#enif_system_info">
+ <p>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 <em>not</em> 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 <seealso marker="#enif_system_info">
<c>enif_system_info()</c></seealso> API function.</p>
</note>
<p>A NIF that cannot be split and cannot execute in a millisecond
@@ -525,7 +525,7 @@ return term;</code>
<p><c>load</c> is called when the NIF library is loaded
and no previously loaded library exists for this module.</p>
<p><c>*priv_data</c> 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. <c>enif_priv_data</c> returns this pointer.
<c>*priv_data</c> is initialized to <c>NULL</c> when <c>load</c> is
called.</p>
@@ -642,9 +642,6 @@ typedef struct {
<p><c>flags</c> can be used to indicate that the NIF is a
<seealso marker="#dirty_nifs">dirty NIF</seealso> that is to be
executed on a dirty scheduler thread.</p>
- <p><em>The dirty NIF functionality described here is
- experimental.</em> You have to enable support for dirty
- schedulers when building OTP to try out the functionality.</p>
<p>If the dirty NIF is expected to be CPU-bound, its <c>flags</c>
field is to be set to <c>ERL_NIF_DIRTY_JOB_CPU_BOUND</c> or
<c>ERL_NIF_DIRTY_JOB_IO_BOUND</c>.</p>
@@ -2488,9 +2485,6 @@ enif_map_iterator_destroy(env, &amp;iter);</code>
application to break up long-running work into multiple regular NIF
calls or to schedule a <seealso marker="#dirty_nifs">
dirty NIF</seealso> to execute on a dirty scheduler thread.</p>
- <p><em>The dirty NIF functionality described here is
- experimental.</em> You have to enable support for dirty
- schedulers when building OTP to try out the functionality.</p>
<taglist>
<tag><c>fun_name</c></tag>
<item>
@@ -2501,7 +2495,7 @@ enif_map_iterator_destroy(env, &amp;iter);</code>
<tag><c>flags</c></tag>
<item>
<p>Must be set to <c>0</c> for a regular NIF. If the emulator was
- built with the experimental dirty scheduler support enabled,
+ built with 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
CPU-bound, or <c>ERL_NIF_DIRTY_JOB_IO_BOUND</c> for