erl_nif.h
Include dependency graph for erl_nif.h:
This graph shows which files directly or indirectly include erl_nif.h:
Public API for nifs, compatible with Erlang/OTP API.
Typedefs
-
typedef term ERL_NIF_TERM
A term.
-
typedef int32_t ErlNifPid
a pid
We currently only handle local pids.
-
typedef struct ResourceType ErlNifResourceType
Opaque resource type.
-
typedef int ErlNifEvent
Selectable event.
-
typedef void ErlNifResourceStop(ErlNifEnv *caller_env, void *obj, ErlNifEvent event, int is_direct_call)
Select stop callback.
-
typedef void ErlNifResourceDown(ErlNifEnv *caller_env, void *obj, ErlNifPid *pid, ErlNifMonitor *mon)
Resource monitor callback.
Enums
-
enum ErlNifSelectFlags
enif_select mode flags
ERL_NIF_SELECT_CANCEL which was introduced with OTP-22, is unimplemented.
Values:
-
enumerator ERL_NIF_SELECT_READ = 1
-
enumerator ERL_NIF_SELECT_WRITE = 2
-
enumerator ERL_NIF_SELECT_STOP = 4
-
enumerator ERL_NIF_SELECT_READ = 1
-
enum [anonymous]
enif_select result flags
ERL_NIF_SELECT_CANCEL which was introduced with OTP-22, is unimplemented.
Values:
-
enumerator ERL_NIF_SELECT_STOP_CALLED = 1
-
enumerator ERL_NIF_SELECT_STOP_SCHEDULED = 2
-
enumerator ERL_NIF_SELECT_INVALID_EVENT = -1
-
enumerator ERL_NIF_SELECT_FAILED = -2
-
enumerator ERL_NIF_SELECT_BADARG = -3
-
enumerator ERL_NIF_SELECT_STOP_CALLED = 1
Functions
-
ErlNifResourceType *enif_init_resource_type(ErlNifEnv *env, const char *name, const ErlNifResourceTypeInit *init, ErlNifResourceFlags flags, ErlNifResourceFlags *tried)
Create or take over (code upgrade) a resource type.
- Parameters:
env – the current environment
init – a structure describing the callbacks. Callbacks can be NULL if not used.
name – name of the resource (copied)
flags –
ERL_NIF_RT_CREATEorERL_NIF_RT_TAKEOVERto create or take over.tried – on output, updated to
ERL_NIF_RT_CREATEorERL_NIF_RT_TAKEOVERdepending on what has been done. On failure, updated to flags. Can be NULL.
- Returns:
the resource type or
NULLon failure.
-
void *enif_alloc_resource(ErlNifResourceType *type, unsigned size)
Allocate a resource for given type for
sizebytes.- Parameters:
type – a trype created by
enif_init_resource_type.size – the size in bytes.
- Returns:
a pointer or
NULLon failure.
-
int enif_get_resource(ErlNifEnv *env, ERL_NIF_TERM t, ErlNifResourceType *type, void **objp)
Get a pointer to a resource from a term representing it.
- Parameters:
env – the current environment
t – the term
type – the resource type
objp – on output the pointer to the resource
- Returns:
trueon success,falseon failure, if term is not a resource of typetype
-
int enif_keep_resource(void *resource)
Increment reference count of a resource.
- Parameters:
resource – the resource to keep
- Returns:
true.
-
int enif_release_resource(void *resource)
Decrement reference count of a resource.
- Parameters:
resource – the resource to release
- Returns:
true.
-
ERL_NIF_TERM enif_make_resource(ErlNifEnv *env, void *obj)
create a term from a resource
the term can be later passed to
enif_get_resource. The resource is typically released (by callingenif_release_resource) just after calling this function to “transfer ownership” to Erlang code so that it will be destroyed when garbage collected.- Parameters:
env – current environment
obj – resource
- Returns:
a new term representing the resource
-
int enif_select(ErlNifEnv *env, ErlNifEvent event, enum ErlNifSelectFlags mode, void *obj, const ErlNifPid *pid, ERL_NIF_TERM ref)
Run a POSIX-like select on a given object (event) and send a message when the object is readable or writable.
Actual implementation is platform dependent and platforms may not implement this feature.
On
generic_unix, this is currently implemented using whatsys_poll_eventsuses, namelykqueue(2)(if available) orpoll(2). Please note thatkqueue(2)andpoll(2)behave differently for some objects, for example for vnodes and EOF.On
esp32, this is currently implemented usingpoll(2).- Parameters:
env – current environment
event – event object (typically a file descriptor)
mode – select mode (
ERL_NIF_SELECT_READand/orERL_NIF_SELECT_WRITE) optionally withERL_NIF_SELECT_CANCELto cancel, orERL_NIF_SELECT_STOPto stop.obj – resource object working as a container of the event object.
pid – process id to send a message to or NULL to use the current process (from
env)ref – reference object used in sent messages or
undefinedatom.
- Returns:
a negative value on failure, 0 or flags on success.
-
int enif_monitor_process(ErlNifEnv *env, void *obj, const ErlNifPid *target_pid, ErlNifMonitor *mon)
Monitor a process by using a resource object.
The monitor is automatically removed after being triggered or if the associated resource is deallocated.
- Parameters:
env – current environment
obj – resource to use for monitor
target_pid – process to monitor
mon – on output, monitor object (can be NULL)
- Returns:
0 on success, <0 if no down callback is provided with resource (badarg), >0 if the process is no longer alive
-
int enif_demonitor_process(ErlNifEnv *caller_env, void *obj, const ErlNifMonitor *mon)
Unmonitor a process.
- Parameters:
caller_env – current environment
obj – resource used by monitor
mon – monitor
- Returns:
0 on success
-
int enif_compare_monitors(const ErlNifMonitor *monitor1, const ErlNifMonitor *monitor2)
compare two monitors
- Parameters:
monitor1 – first monitor
monitor2 – second monitor
- Returns:
0 if equals, < 0 if
monitor1<monitor2, > 0 ifmonitor1>monitor2.
-
struct ErlNifMonitor
- #include <erl_nif.h>
Collaboration diagram for ErlNifMonitor:
Opaque monitor type.
-
struct ErlNifResourceTypeInit
- #include <erl_nif.h>
Resource callbacks.
Members should be set to 0, 1 or 2 depending on provided callbacks. Callbacks can also be NULL if not used.
Public Members
-
int members
-
ErlNifResourceDtor *dtor
-
ErlNifResourceStop *stop
-
ErlNifResourceDown *down
-
int members