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 struct ErlNifEnv ErlNifEnv

Opaque environment, passed to nifs.

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 ErlNifResourceDtor(ErlNifEnv *caller_env, void *obj)

Destructor callback.

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 ErlNifResourceFlags

resource flags

Values:

enumerator ERL_NIF_RT_CREATE = 1

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

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

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_CREATE or ERL_NIF_RT_TAKEOVER to create or take over.

• tried – on output, updated to ERL_NIF_RT_CREATE or ERL_NIF_RT_TAKEOVER depending on what has been done. On failure, updated to flags. Can be NULL.

Returns:

the resource type or NULL on failure.

void *enif_alloc_resource(ErlNifResourceType *type, unsigned size)

Allocate a resource for given type for size bytes.

following BEAM semantics, the resource is created with a refcount of 1. A call to enif_release_resource will decrement the refcount and destroy the resource if it is zero.

Typical usage (as suggested by BEAM documentation) is to call enif_make_resource and then enif_release_resource to somewhat transfer ownership to the garbage collector. enif_make_resource will increment refcount to 2 and also add the resource to the MSO list of the context, so when the term is no longer referenced in the context heap, the reference counter will be decremented by gc.

Parameters:

• type – a trype created by enif_init_resource_type.

• size – the size in bytes.

Returns:

a pointer or NULL on 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:

true on success, false on failure, if term is not a resource of type type

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 reference counter is incremented and it is added to the MSO list of the heap of env (which must be a context).

If the resource was just allocated with enif_alloc_resource, the reference counter should typically be decremented by a call to enif_release_resource matching usage documented by BEAM.

If the resource was not just allocated with enif_alloc_resource, to clear usage confusion, users should rather call term_from_resource and should not decrement the reference counter.

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 what sys_poll_events uses, namely kqueue(2) (if available) or poll(2). Please note that kqueue(2) and poll(2) behave differently for some objects, for example for vnodes and EOF.

On esp32, this is currently implemented using poll(2).

Parameters:

• env – current environment

• event – event object (typically a file descriptor)

• mode – select mode (ERL_NIF_SELECT_READ and/or ERL_NIF_SELECT_WRITE) optionally with ERL_NIF_SELECT_CANCEL to cancel, or ERL_NIF_SELECT_STOP to 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 undefined atom.

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 if monitor1 > monitor2.

struct ErlNifMonitor

#include <erl_nif.h>

Collaboration diagram for ErlNifMonitor:

Opaque monitor type.

Public Members

struct ResourceType *resource_type

uint64_t ref_ticks

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