From 0763a36867a702e3075b682973a079e0390144ce Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Wed, 23 Nov 2016 15:58:15 +0100 Subject: erts: Add enif_select & enif_open_resource_type_x --- erts/doc/src/erl_nif.xml | 84 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 906c1be17b..e7073a962f 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -699,12 +699,30 @@ typedef struct { Each resource type has a unique name and a destructor function that is called when objects of its type are released.

+ ErlNifResourceTypeInit + + +typedef struct { + ErlNifResourceDtor* dtor; + ErlNifResourceStop* stop; +} ErlNifResourceTypeInit; +

Initialization structure read by + enif_open_resource_type_x.

+ ErlNifResourceDtor typedef void ErlNifResourceDtor(ErlNifEnv* env, void* obj);

The function prototype of a resource destructor function.

 + ErlNifResourceStop + + +typedef void ErlNifResourceStop(ErlNifEnv* env, void* obj); +

The function prototype of a resource stop function, + called on the behalf of + enif_select.

+ ErlNifCharEncoding @@ -2238,6 +2256,24 @@ enif_map_iterator_destroy(env, &iter); + + ErlNifResourceType * + enif_open_resource_type_x(ErlNifEnv* env, const char* name, + 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.

+

Argument init is a pointer to an + ErlNifResourceTypeInit + structure that contains the function pointers for the destructor and the stop callback + of the resource type.

+ + + intenif_port_command(ErlNifEnv* env, const ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg) @@ -2345,7 +2381,7 @@ enif_map_iterator_destroy(env, &iter); enif_release_resource(void* obj) Release a resource object. -

Removes a reference to resource object objobtained from +

Removes a reference to resource object obj obtained from enif_alloc_resource. The resource object is destructed when the last reference is removed. @@ -2487,6 +2523,52 @@ enif_map_iterator_destroy(env, &iter); + + int + enif_select(ErlNifEnv* env, ErlNifEvent event, + enum ErlNifSelectFlags mode, void* obj, Eterm ref) + + Manage subscription on IO event. + +

This function can be used to receive asynchronous notifications + when OS-specific event objects become ready for either read or write operations.

+

Argument event identifies the event object. On Unix + systems, the functions select/poll are used. The event + object must be a socket, pipe or other file descriptor object that + select/poll can use.

+

Argument mode describes the type of events to wait for. It can be + ERL_NIF_SELECT_READ, ERL_NIF_SELECT_WRITE or a bitwise + OR combination to wait for both. It can also be ERL_NIF_SELECT_STOP + which is described further below. When a read or write event is triggerred, + a notification message like this is sent to the Erlang process that called + enif_select:

+ {select, Obj, Ref, ready_input | ready_output} +

ready_input or ready_output indicates if the event object + is ready for reading or writing.

+

Argument obj is a resource object obtained from + enif_alloc_resource. + The purpose of the resource objects is as a container of the event object + to manage its state and lifetime. A handle to the resource is received + in the notification message as Obj.

+

Argument ref must be either a reference obtained from + erlang:make_ref/0 + or the atom undefined. It will be passed as Ref in the notifications. + If a selective receive statement is used to wait for the notification + then a reference created just before the receive will exploit a runtime + optimization that bypasses all earlier received messages in the queue.

+

The notifications are one-shot only. To receive further notifications of the same + type (read or write), repeated calls to enif_select must be made.

+

Use ERL_NIF_SELECT_STOP as mode in order to safely + close an event object that has been passed to enif_select. The + stop callback + of the resource obj will be called when it is safe to close + 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.

+

Returns 0 on success, or -1 if invalid arguments.

+ + + ErlNifPid * enif_self(ErlNifEnv* caller_env, ErlNifPid* pid) -- cgit v1.2.3