From 8222631bd1aa0e0fb8fea52bc984865d4433d182 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Tue, 9 May 2017 21:26:09 +0200 Subject: erts: Improve erl_nif docs --- erts/doc/src/erl_nif.xml | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) (limited to 'erts/doc/src') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 51ba70994a..3eb3e04f33 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -714,6 +714,7 @@ typedef struct { typedef struct { ErlNifResourceDtor* dtor; ErlNifResourceStop* stop; + ErlNifResourceDown* down; } ErlNifResourceTypeInit;

Initialization structure read by enif_open_resource_type_x.

@@ -1395,13 +1396,12 @@ typedef enum {

Returns true if a pending exception is associated with the environment env. If reason is a NULL pointer, ignore it. Otherwise, if a pending exception associated with - env exists, set ERL_NIF_TERM to which reason - points to the value of the exception's term. For example, if - + env exists, set *reason to the value of the exception + term. For example, if enif_make_badarg is called to set a pending badarg exception, a later call to enif_has_pending_exception(env, &reason) sets - reason to the atom badarg, then return true.

+ *reason to the atom badarg, then return true.

See also enif_make_badarg and @@ -2384,20 +2384,23 @@ enif_map_iterator_destroy(env, &iter); called in the two callbacks load and upgrade.

+

See also + enif_open_resource_type_x.

ErlNifResourceType * enif_open_resource_type_x(ErlNifEnv* env, const char* name, - ErlNifResourceTypeInit* init, + const ErlNifResourceTypeInit* init, ErlNifResourceFlags flags, ErlNifResourceFlags* tried) Create or takeover a resource type.

Same as enif_open_resource_type - except is also accept a stop callback for resource types that are - used together with enif_select.

+ except it accepts additional callback functions for resource types that are + used together with enif_select + and enif_monitor_process.

Argument init is a pointer to an ErlNifResourceTypeInit structure that contains the function pointers for destructor, down and stop callbacks @@ -2695,6 +2698,21 @@ enif_map_iterator_destroy(env, &iter); the event object. This safe way of closing event objects must be used even if all notifications have been received and no further calls to enif_select have been made.

+

The first call to enif_select for a specific OS event will establish + a relation between the event object and the containing resource. All subsequent calls + for an event must pass its containing resource as argument + obj. The relation is dissolved when enif_select has + been called with mode as ERL_NIF_SELECT_STOP and the + corresponding stop callback has returned. A resource can contain + several event objects but one event object can only be contained within + one resource. A resource will not be destructed until all its contained relations + have been dissolved.

+ +

Use enif_monitor_process + together with enif_select to detect failing Erlang + processes and prevent them from causing permanent leakage of resources + and their contained OS event objects.

+

Returns a non-negative value on success where the following bits can be set:

ERL_NIF_SELECT_STOP_CALLED -- cgit v1.2.3