erl_nif
Warning!
The NIF concept is introduced in R13B03 as an EXPERIMENTAL feature. The interfaces may be changed in any way in coming releases. The API introduced in this release is very sparse and contains only the most basic functions to read and write Erlang terms.
A NIF library contains native implementation of some functions of an erlang module. The native implemented functions (NIFs) are called like any other functions without any difference to the caller. Each NIF must also have an implementation in Erlang that will be invoked if the function is called before the NIF library has been successfully loaded. A typical such stub implementation is to throw an exception. But it can also be used as a fallback implementation if the NIF library is not implemented for some architecture.
A minimal example of a NIF library can look like this:
/* niftest.c */ #include "erl_nif.h" static ERL_NIF_TERM hello(ErlNifEnv* env) { return enif_make_string(env, "Hello world!"); } static ErlNifFunc nif_funcs[] = { {"hello", 0, hello} }; ERL_NIF_INIT(niftest,nif_funcs,NULL,NULL,NULL,NULL)
and the erlang module would have to look something like this:
-module(niftest). -export([init/0, hello/0]). init() -> erlang:load_nif("./niftest", 0). hello() -> "NIF library not loaded".
and compile and test something like this (on Linux):
$> gcc -fPIC -shared -o niftest.so niftest.c -I $ERL_ROOT/usr/include/ $> erl 1> c(niftest). {ok,niftest} 2> niftest:hello(). "NIF library not loaded" 3> niftest:init(). ok 4> niftest:hello(). "Hello world!"
A better solution for a real module is to take advantage of
the new attribute on_load
to automatically load the NIF
library when the module is loaded.
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 code will have to load its own NIF library (or maybe choose not to). The new code version can however choose to load the exact same NIF library as the old code if it wants to. Sharing the same dynamic library will mean that static data defined by the library will be shared as well. To avoid unintentionally shared static data, each Erlang module code can keep its own private data. This global private data can be set when the NIF library is loaded and then retrieved by calling enif_get_data().
There is currently no way to explicitly unload a NIF
library. A library will be automatically unloaded when the module
code that it belongs to is purged by the code server. A NIF
library will can also be unloaded by replacing it with another
version of the library by a second call to
erlang:load_nif/2
from the same module code.
INITIALIZATION
- ERL_NIF_INIT(MODULE, ErlNifFunc funcs[], load, reload, upgrade, unload)
This is the magic macro to initialize a NIF library. It should be evaluated in global file scope.
MODULE
is the name of the Erlang module as an identifier without string quotations. It will be stringified by the macro.funcs
is a static array of function descriptors for all the implemented NIFs in this library.load
,reload
,upgrade
andunload
are pointers to functions. One ofload
,reload
orupgrade
will be called to initialize the library.unload
is called to release the library. They are all described individually below.- int (*load)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)
load
is called when the NIF library is loaded and there is no previously loaded library for this module.*priv_data
can be set to point to some private data that the library needs in able to keep a state between NIF calls.enif_get_data()
will return this pointer.load_info
is the second argument to erlang:load_nif/2.The library will fail to load if
load
returns anything other than 0.load
can be NULL in case no initialization is needed.- int (*reload)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)
reload
is called when the NIF library is loaded and there is already a previously loaded library for this module code.Works the same as
load
. The only difference is that*priv_data
already contains the value set by the previous call toload
orreload
.The library will fail to load if
reload
returns anything other than 0 or ifreload
is NULL.- int (*upgrade)(ErlNifEnv* env, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info)
upgrade
is called when the NIF library is loaded and there is no previously loaded library for this module code, BUT there is old code of this module with a loaded NIF library.Works the same as
load
. The only difference is that*old_priv_data
already contains the value set by the last call toload
orreload
for the old module code. It is allowed to write to both *priv_data and *old_priv_data.The library will fail to load if
upgrade
returns anything other than 0 or ifupgrade
is NULL.- void (*unload)(ErlNifEnv* env, void* priv_data)
unload
is called when the module code that the NIF library belongs to is purged as old. New code of the same module may or may not exist.
DATA TYPES
- ErlDrvEnv
-
ErlNifEnv
contains information about the context in which a NIF call is made. This pointer should not be dereferenced in any way, but only passed on to API functions. AnErlNifEnv
pointer is only valid until the function, where is what supplied as argument, returns. There is thus useless and dangerous to storeErlNifEnv
pointers in between NIF calls. - ErlNifFunc
-
typedef struct { const char* name; unsigned arity; ERL_NIF_TERM (*fptr)(ErlNifEnv* env, ...); } ErlNifFunc;
Describes a NIF by its name, arity and implementation.
fptr
is a pointer to the function that implements the NIF. The number of arguments must match the arity. A NIF of arity 2 will thus look like:ERL_NIF_TERM my_nif(ErlNifEnv* env, ERL_NIF_TERM arg1, ERL_NIF_TERM arg2) { /* ... */ }
The maximum allowed arity for a NIF is 3 in current implementation.
- ErlNifBinary
-
typedef struct { unsigned size; unsigned char* data; } ErlNifBinary;
ErlNifBinary
contains transient information about an inspected binary term.data
is a pointer to a buffer ofsize
bytes with the raw content of the binary. - ERL_NIF_TERM
-
Variables of type
ERL_NIF_TERM
can refere to any Erlang term. This is an opaque type and values of it can only by used either as arguments to API functions or as return values from NIFs. A variable of typeERL_NIF_TERM
is only valid until the NIF call, where it was obtained, returns.
Functions
Returns the pointer to the private data that was set by load
, reload
or upgrade
.
Allocate memory of size
bytes.
Free memory allocated by enif_alloc
.
Return true if term
is a binary
Initialize the structure pointed to by bin
with
transient information about the binary term
bin_term
. Return false if bin_term
is not a binary.
Allocate a new binary of size of size
bytes. Initialize the structure pointed to by bin
to
refer to the allocated binary.
Release a binary obtained from enif_alloc_binary
or enif_inspect_binary
.
Set *ip
to the integer value of
term
or return false if term
is not an integer or is
outside the bounds of type int
Set *ip
to the unsigned long integer value of
term
or return false if term
is not an unsigned
integer or is outside the bounds of type unsigned long
Set *head
and *tail
from
list
or return false if list
is not a non-empty
list.
Make a binary term from bin
. Will also release
the binary.
Make a badarg exception to be returned from a NIF.
Create an integer term.
Create an integer term from an unsigned long int
.
Create an atom term from the C-string name
. Atom
terms may be saved and used between NIF calls.
Create a tuple term of arity cnt
. Expects
cnt
number of arguments (after cnt
) of type ERL_NIF_TERM as the
elements of the tuple.
Create an ordinary list term of length cnt
. Expects
cnt
number of arguments (after cnt
) of type ERL_NIF_TERM as the
elements of the list. An empty list is returned if cnt
is 0.
Create a list cell [head | tail]
.
Creates a list containing the characters of the
C-string string
.