resources.c

Include dependency graph for resources.c:

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.

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 is typically released (by calling enif_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 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.

term select_event_make_notification(void *rsrc_obj, uint64_t ref_ticks, bool is_write, Heap *heap)

Build a select event notification.

Parameters:

• rsrc_obj – the resource to build the notification for

• ref_ticks – the reference or 0 if it’s undefined

• is_write – if the notification is for a write or a read

• heap – the heap to create the notification in, should have enough memory available (see SELECT_EVENT_NOTIFICATION_SIZE)

static void select_event_send_notification(struct SelectEvent *select_event, bool is_write, GlobalContext *global)

bool select_event_notify(ErlNifEvent event, bool is_read, bool is_write, GlobalContext *global)

Send a notification that an event was selected.

This function is called from sys_poll_events platform function if a select event was selected and the read or write flag was set. It modifies the select_event object so the notification is only sent once.

The function can also be called from a select task loop if AVM_SELECT_IN_TASK is defined.

It is not an error to call this function with an event that is not in the list.

This function calls sys_unregister_select_event.

Parameters:

• event – the event to notify

• is_read – if the event was selected for reading

• is_write – if the event was selected for writing

• global – the global context

Returns:

true if the event was found

static inline void select_event_destroy(struct SelectEvent *select_event, GlobalContext *global)

void select_event_count_and_destroy_closed(struct ListHead *select_events, size_t *read, size_t *write, size_t *either, GlobalContext *global)

Count events available for reading and/or writing and destroy the events marked for close.

Convenience function that can be called by sys_poll_events and iterates on events to be closed and count them.

The function can also be called from a select task loop if AVM_SELECT_IN_TASK is defined.

Parameters:

• select_events – list of events, with a write lock

• read – on output number of events with read = 1, can be NULL

• write – on output number of events with write = 1, can be NULL

• either – on output number of events with either read = 1 or write = 1, can be NULL

• global – the global context

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 *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

void destroy_resource_monitors(struct RefcBinary *resource, GlobalContext *global)

Destroy monitors associated with a resource.

Parameters:

• resource – resource to destroy monitors for

• global – the global context

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.