erl_nif

*

A native function that crashes will crash the whole VM.

*

An erroneously implemented native function can cause a VM internal state inconsistency, which can cause a crash of the VM, or miscellaneous misbehaviors of the VM at any point after the call to the native function.

*

A native function doing lengthy work before returning degrades responsiveness of the VM, and can cause miscellaneous strange behaviors. Such strange behaviors include, but are not limited to, extreme memory usage, and bad load balancing between schedulers. Strange behaviors that can occur because of lengthy work can also vary between Erlang/OTP releases.

Read and write Erlang terms:

Any Erlang terms can be passed to a NIF as function arguments and be returned as function return values. The terms are of C-type ERL_NIF_TERM and can only be read or written using API functions. Most functions to read the content of a term are prefixed enif_get_ and usually return true (or false) if the term is of the expected type (or not). The functions to write terms are all prefixed enif_make_ and usually return the created ERL_NIF_TERM. There are also some functions to query terms, like enif_is_atom, enif_is_identical, and enif_compare.

Binaries:

Terms of type binary are accessed with the help of struct type ErlNifBinary, which contains a pointer (data) to the raw binary data and the length ( size) of the data in bytes. Both data and size are read-only and are only to be written using calls to API functions. Instances of ErlNifBinary are, however, always allocated by the user (usually as local variables).

Resource objects:

The use of resource objects is a safe way to return pointers to native data structures from a NIF. A resource object is only a block of memory allocated with enif_alloc_resource. A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of enif_make_resource. The term returned by enif_make_resource is opaque in nature. It can be stored and passed between processes, but the only real end usage is to pass it back as an argument to a NIF. The NIF can then call enif_get_resource and get back a pointer to the memory block, which is guaranteed to still be valid. A resource object is not deallocated until the last handle term is garbage collected by the VM and the resource is released with enif_release_resource (not necessarily in that order).

ERL_NIF_TERM term;
MyStruct* obj = enif_alloc_resource(my_resource_type, sizeof(MyStruct));

/* initialize struct ... */

term = enif_make_resource(env, obj);

if (keep_a_reference_of_our_own) {
    /* store 'obj' in static variable, private data or other resource object */
}
else {
    enif_release_resource(obj);
    /* resource now only owned by "Erlang" */
}
return term;

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 long as it acts as a pure function and only reads the supplied arguments. When you write to a shared state either through static variables or enif_priv_data, you need to supply your own explicit synchronization. This includes terms in process independent environments that are shared between threads. Resource objects also require synchronization if you treat them as mutable.

Version Management:

When a NIF library is built, information about the NIF API version is compiled into the library. When a NIF library is loaded, the runtime system verifies that the library is of a compatible version. erl_nif.h defines the following:

Time Measurement:

Support for time measurement in NIF libraries:

I/O Queues:

The Erlang nif library contains function for easily working with I/O vectors as used by the unix system call writev. The I/O Queue is not thread safe, so some other synchronization mechanism has to be used.

int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
               ErlNifIOQueue *q, int fd) {

    ErlNifIOVec vec, *iovec = &vec;
    SysIOVec *sysiovec;
    int saved_errno;
    int iovcnt, n;

    if (!enif_inspect_iovec(env, 64, term, tail, &iovec))
        return -2;

    if (enif_ioq_size(q) > 0) {
        /* If the I/O queue contains data we enqueue the iovec and
           then peek the data to write out of the queue. */
        if (!enif_ioq_enqv(q, iovec, 0))
            return -3;

        sysiovec = enif_ioq_peek(q, &iovcnt);
    } else {
        /* If the I/O queue is empty we skip the trip through it. */
        iovcnt = iovec->iovcnt;
        sysiovec = iovec->iov;
    }

    /* Attempt to write the data */
    n = writev(fd, sysiovec, iovcnt);
    saved_errno = errno;

    if (enif_ioq_size(q) == 0) {
        /* If the I/O queue was initially empty we enqueue any
           remaining data into the queue for writing later. */
        if (n >= 0 && !enif_ioq_enqv(q, iovec, n))
            return -3;
    } else {
        /* Dequeue any data that was written from the queue. */
        if (n > 0 && !enif_ioq_deq(q, n, NULL))
            return -4;
    }

    /* return n, which is either number of bytes written or -1 if
       some error happened */
    errno = saved_errno;
    return n;
}

Long-running NIFs:

As mentioned in the warning text at the beginning of this manual page, it is of vital importance that a native function returns relatively fast. It is difficult to give an exact maximum amount of time that a native function is allowed to work, but usually a well-behaving native function is to return to its caller within 1 millisecond. This can be achieved using different approaches. If you have full control over the code to execute in the native function, the best approach is to divide the work into multiple chunks of work and call the native function multiple times. This is, however, not always possible, for example when calling third-party libraries.

ERL_NIF_INIT(MODULE, ErlNifFunc funcs[], load, NULL, upgrade, unload):

This is the magic macro to initialize a NIF library. It is to be evaluated in global file scope.

int (*load)(ErlNifEnv* caller_env, void** priv_data, ERL_NIF_TERM load_info):

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

int (*upgrade)(ErlNifEnv* caller_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 old code of this module with a loaded NIF library.

void (*unload)(ErlNifEnv* caller_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.

ERL_NIF_TERM:

Variables of type ERL_NIF_TERM can refer 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. All ERL_NIF_TERMs belong to an environment (ErlNifEnv). A term cannot be destructed individually, it is valid until its environment is destructed.

ErlNifEnv:

ErlNifEnv represents an environment that can host Erlang terms. All terms in an environment are valid as long as the environment is valid. ErlNifEnv is an opaque type; pointers to it can only be passed on to API functions. Three types of environments exist:

ErlNifFunc:

typedef struct {
    const char* name;
    unsigned arity;
    ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
    unsigned flags;
} ErlNifFunc;

ErlNifBinary:

typedef struct {
    size_t size;
    unsigned char* data;
} ErlNifBinary;

ErlNifBinaryToTerm:

An enumeration of the options that can be specified to enif_binary_to_term. For default behavior, use value 0.

ErlNifMonitor:

This is an opaque data type that identifies a monitor.

ErlNifPid:

A process identifier (pid). In contrast to pid terms (instances of ERL_NIF_TERM), ErlNifPids are self-contained and not bound to any environment. ErlNifPid is an opaque type. It can be copied, moved in memory, forgotten, and so on.

ErlNifPort:

A port identifier. In contrast to port ID terms (instances of ERL_NIF_TERM), ErlNifPorts are self-contained and not bound to any environment. ErlNifPort is an opaque type. It can be copied, moved in memory, forgotten, and so on.

ErlNifResourceType:

Each instance of ErlNifResourceType represents a class of memory-managed resource objects that can be garbage collected. Each resource type has a unique name and a destructor function that is called when objects of its type are released.

ErlNifResourceTypeInit:

typedef struct {
    ErlNifResourceDtor* dtor;       // #1 Destructor
    ErlNifResourceStop* stop;       // #2 Select stop
    ErlNifResourceDown* down;       // #3 Monitor down
    int members;
    ErlNifResourceDynCall* dyncall; // #4 Dynamic call
} ErlNifResourceTypeInit;

ErlNifResourceDtor:

typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);

ErlNifResourceDown:

typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);

ErlNifResourceStop:

typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);

ErlNifResourceDynCall:

typedef void ErlNifResourceDynCall(ErlNifEnv* caller_env, void* obj, void* call_data);

ErlNifCharEncoding:

typedef enum {
    ERL_NIF_LATIN1
}ErlNifCharEncoding;

ErlNifSysInfo:

Used by enif_system_info to return information about the runtime system. Contains the same content as ErlDrvSysInfo.

ErlNifSInt64:

A native signed 64-bit integer type.

ErlNifUInt64:

A native unsigned 64-bit integer type.

ErlNifTime:

A signed 64-bit integer type for representation of time.

ErlNifTimeUnit:

An enumeration of time units supported by the NIF API:

ErlNifUniqueInteger:

An enumeration of the properties that can be requested from enif_make_unique_integer. For default properties, use value 0.

ErlNifHash:

An enumeration of the supported hash types that can be generated using enif_hash.

SysIOVec:

A system I/O vector, as used by writev on Unix and WSASend on Win32. It is used in ErlNifIOVec and by enif_ioq_peek.

ErlNifIOVec:

typedef struct {
  int iovcnt;
  size_t size;
  SysIOVec* iov;
} ErlNifIOVec;

ErlNifIOQueueOpts:

Options to configure a ErlNifIOQueue.

ErlNifIOVec *iovec = NULL;
size_t max_elements = 128;
ERL_NIF_TERM tail;
if (!enif_inspect_iovec(NULL, max_elements, term, &tail, &iovec))
  return 0;

// Do things with the iovec

/* Free the iovector, possibly in another thread or nif function call */
enif_free_iovec(iovec);

/* Don't use a pre-allocated structure */
ErlNifIOVec *iovec = NULL;
enif_inspect_iovec(env, max_elements, term, &tail, &iovec);

/* Use a stack-allocated vector as an optimization for vectors with few elements */
ErlNifIOVec vec, *iovec = &vec;
enif_inspect_iovec(env, max_elements, term, &tail, &iovec);

ERL_NIF_TERM key, value;
ErlNifMapIterator iter;
enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST);

while (enif_map_iterator_get_pair(env, &iter, &key, &value)) {
    do_something(key,value);
    enif_map_iterator_next(env, &iter);
}
enif_map_iterator_destroy(env, &iter);

{select, Obj, Ref, ready_input | ready_output}

retval = enif_select(env, fd, ERL_NIF_SELECT_STOP, resource, ref);
if (retval < 0) {
    /* handle error */
}
/* Success! */
if (retval & ERL_NIF_SELECT_STOP_CALLED) {
    /* ... */
}