From 614a1b7dbfc7ce1bc9ae7d4e946feb5efc26d0f6 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Tue, 19 Feb 2019 15:27:13 +0100 Subject: erts: Clarify erl_nif docs for enif_send and enif_select_read|write. --- erts/doc/src/erl_nif.xml | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 95b7188882..d58ebd3171 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -3091,16 +3091,18 @@ enif_map_iterator_destroy(env, &iter); 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.

+ 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 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.

+ indicate which type of event to cancel. Arguments pid and + ref are ignored when ERL_NIF_SELECT_CANCEL is specified. + 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 @@ -3109,7 +3111,9 @@ enif_map_iterator_destroy(env, &iter); 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.

+ before it calls or schedules the stop callback. Arguments + pid and ref are ignored when ERL_NIF_SELECT_STOP + is specified.

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 @@ -3192,7 +3196,11 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { enif_alloc_env. If argument msg_env is NULL the term msg will be copied, otherwise both msg and msg_env will be invalidated by a successful call - to enif_select_read or enif_select_write.

+ to enif_select_read or enif_select_write. The environment + is then to either be freed with + enif_free_env or cleared for reuse with + enif_clear_env. An + unsuccessful call will leave msg and msg_env still valid.

Apart from the message format enif_select_read and enif_select_write behaves exactly the same as enif_select with argument mode as @@ -3246,8 +3254,9 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) { msg) is invalidated by a successful call to enif_send. The environment is to either be freed with - enif_free_env of cleared for reuse with - enif_clear_env.

+ enif_free_env or cleared for reuse with + enif_clear_env. An + unsuccessful call will leave msg and msg_env still valid.

If msg_env is set to NULL, the msg term is copied and the original term and its environment is still valid after the call.

-- cgit v1.2.3