From 31d26cfc44e0b0bb84879e7043db4dcf4e0e66cc Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Fri, 20 Jul 2018 15:43:14 +0200 Subject: erts: Add ERL_NIF_SELECT_CANCEL flag for enif_select to deselect read and/or writes without stop callback. --- erts/doc/src/erl_nif.xml | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index a20b8ee884..a5826307f7 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -3037,7 +3037,8 @@ enif_map_iterator_destroy(env, &iter);

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 triggered, + or ERL_NIF_SELECT_CANCEL which are described further + below. When a read or write event is triggered, a notification message like this is sent to the process identified by pid:

{select, Obj, Ref, ready_input | ready_output} @@ -3058,13 +3059,21 @@ enif_map_iterator_destroy(env, &iter);

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 after receiving each notification.

+

ERL_NIF_SELECT_CANCEL can be used to cancel previously + selected events. It must be used in a bitwise OR combination with + ERL_NIF_SELECT_READ and/or ERL_NIF_SELECT_WRITE to + indicate which type of event to cancel. The return value will + tell if the event was actualy cancelled or if a notification may + already have been sent.

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.

+ even if all notifications have been received (or cancelled) and no + further calls to enif_select have been made. + ERL_NIF_SELECT_STOP will first cancel any selected events + before it calls or schedules the stop callback.

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 @@ -3086,7 +3095,15 @@ enif_map_iterator_destroy(env, &iter); The stop callback was called directly by enif_select. ERL_NIF_SELECT_STOP_SCHEDULED The stop callback was scheduled to run on some other thread - or later by this thread. + or later by this thread. + ERL_NIF_SELECT_READ_CANCELLED + A read event was cancelled by ERL_NIF_SELECT_CANCEL or + ERL_NIF_SELECT_STOP and is guaranteed not to generate a + ready_input notification message. + ERL_NIF_SELECT_WRITE_CANCELLED + A write event was cancelled by ERL_NIF_SELECT_CANCEL or + ERL_NIF_SELECT_STOP and is guaranteed not to generate a + ready_output notification message.

Returns a negative value if the call failed where the following bits can be set:

@@ -3112,6 +3129,11 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { } +

The mode flag ERL_NIF_SELECT_CANCEL and the return flags + ERL_NIF_SELECT_READ_CANCELLED and + ERL_NIF_SELECT_WRITE_CANCELLED were introduced in erts-11.0 + (OTP-22.0).

+ -- cgit v1.2.3