-
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_TERM
s 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:
-
Process bound environment
-
Passed as the first argument to all NIFs. All function arguments passed to a NIF belong to that environment. The return value from a NIF must also be a term belonging to the same environment.
A process bound environment contains transient information about the calling Erlang process. The environment is only valid in the thread where it was supplied as argument until the NIF returns. It is thus useless and dangerous to store pointers to process bound environments between NIF calls.
-
Callback environment
-
Passed as the first argument to all the non-NIF callback functions (load
, upgrade
, unload
, dtor
, down
, stop
and dyncall
). Works like a process bound environment but with a temporary pseudo process that "terminates" when the callback has returned. Terms may be created in this environment but they will only be accessible during the callback.
-
Process independent environment
-
Created by calling enif_alloc_env
. This environment can be used to store terms between NIF calls and to send terms with enif_send
. A process independent environment with all its terms is valid until you explicitly invalidate it with enif_free_env
or enif_send
.
All contained terms of a list/tuple/map must belong to the same environment as the list/tuple/map itself. Terms can be copied between environments with enif_make_copy
.
-
ErlNifFunc
-
typedef struct {
const char* name;
unsigned arity;
ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
unsigned flags;
} ErlNifFunc;
Describes a NIF by its name, arity, and implementation.
-
fptr
-
A pointer to the function that implements the NIF.
-
argv
-
Contains the function arguments passed to the NIF.
-
argc
-
The array length, that is, the function arity. argv[N-1]
thus denotes the Nth argument to the NIF. Notice that the argument argc
allows for the same C function to implement several Erlang functions with different arity (but probably with the same name).
-
flags
-
Is 0
for a regular NIF (and so its value can be omitted for statically initialized ErlNifFunc
instances).
flags
can be used to indicate that the NIF is a dirty NIF
that is to be executed on a dirty scheduler thread.
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
.
Note
If one of the ERL_NIF_DIRTY_JOB_*_BOUND
flags is set, and the runtime system has no support for dirty schedulers, the runtime system refuses to load the NIF library.
-
ErlNifBinary
-
typedef struct {
size_t size;
unsigned char* data;
} ErlNifBinary;
ErlNifBinary
contains transient information about an inspected binary term. data
is a pointer to a buffer of size
bytes with the raw content of the binary.
Notice that ErlNifBinary
is a semi-opaque type and you are only allowed to read fields size
and data
.
-
ErlNifBinaryToTerm
-
An enumeration of the options that can be specified to enif_binary_to_term
. For default behavior, use value 0
.
When receiving data from untrusted sources, use option ERL_NIF_BIN2TERM_SAFE
.
-
ErlNifMonitor
-
This is an opaque data type that identifies a monitor.
The nif writer is to provide the memory for storing the monitor when calling enif_monitor_process
. The address of the data is not stored by the runtime system, so ErlNifMonitor
can be used as any other data, it can be copied, moved in memory, forgotten, and so on. To compare two monitors, enif_compare_monitors
must be used.
-
ErlNifPid
-
A process identifier (pid). In contrast to pid terms (instances of ERL_NIF_TERM
), ErlNifPid
s 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
), ErlNifPort
s 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;
Initialization structure read by enif_open_resource_type_x
enif_init_resource_type
.
-
ErlNifResourceDtor
-
typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);
The function prototype of a resource destructor function.
The obj
argument is a pointer to the resource. The only allowed use for the resource in the destructor is to access its user data one final time. The destructor is guaranteed to be the last callback before the resource is deallocated.
-
ErlNifResourceDown
-
typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);
The function prototype of a resource down function, called on the behalf of enif_monitor_process
. obj
is the resource, pid
is the identity of the monitored process that is exiting, and mon
is the identity of the monitor.
-
ErlNifResourceStop
-
typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);
The function prototype of a resource stop function, called on the behalf of enif_select
. obj
is the resource, event
is OS event, is_direct_call
is true if the call is made directly from enif_select
or false if it is a scheduled call (potentially from another thread).
-
ErlNifResourceDynCall
-
typedef void ErlNifResourceDynCall(ErlNifEnv* caller_env, void* obj, void* call_data);
The function prototype of a dynamic resource call function, called by enif_dynamic_resource_call
. Argument obj
is the resource object and call_data
is the last argument to enif_dynamic_resource_call
passed through.
-
ErlNifCharEncoding
-
typedef enum {
ERL_NIF_LATIN1
}ErlNifCharEncoding;
The character encoding used in strings and atoms. The only supported encoding is ERL_NIF_LATIN1
for ISO Latin-1 (8-bit ASCII).
-
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:
-
ERL_NIF_SEC
-
Seconds
-
ERL_NIF_MSEC
-
Milliseconds
-
ERL_NIF_USEC
-
Microseconds
-
ERL_NIF_NSEC
-
Nanoseconds
-
ErlNifUniqueInteger
-
An enumeration of the properties that can be requested from enif_make_unique_integer
. For default properties, use value 0
.
-
ERL_NIF_UNIQUE_POSITIVE
-
Return only positive integers.
-
ERL_NIF_UNIQUE_MONOTONIC
-
Return only strictly monotonically increasing
integer corresponding to creation time.
-
ErlNifHash
-
An enumeration of the supported hash types that can be generated using enif_hash
.
-
ERL_NIF_INTERNAL_HASH
-
Non-portable hash function that only guarantees the same hash for the same term within one Erlang VM instance.
It takes 32-bit salt values and generates hashes within 0..2^32-1
.
-
ERL_NIF_PHASH2
-
Portable hash function that gives the same hash for the same Erlang term regardless of machine architecture and ERTS version.
It ignores salt values and generates hashes within 0..2^27-1
.
Slower than ERL_NIF_INTERNAL_HASH.
It corresponds to erlang:phash2/1
.
-
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;
An I/O vector containing iovcnt
SysIOVec
s pointing to the data. It is used by enif_inspect_iovec
and enif_ioq_enqv
.
-
ErlNifIOQueueOpts
-
Options to configure a
ErlNifIOQueue
.
-
ERL_NIF_IOQ_NORMAL
-
Create a normal I/O Queue