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