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
orERL_NIF_RT_TAKEOVER
to create or take over.tried – on output, updated to
ERL_NIF_RT_CREATE
orERL_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 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_events
uses, 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_READ
and/orERL_NIF_SELECT_WRITE
) optionally withERL_NIF_SELECT_CANCEL
to cancel, orERL_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 ifmonitor1
>monitor2
.