From 4c5d33114edea787833d6aa1b0d51ea9d98b3321 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson
Date: Fri, 16 Dec 2016 19:30:22 +0100
Subject: Add ErlNifSelectReturn
---
erts/doc/src/erl_nif.xml | 35 +++++++++++++++++++++++++++++++++--
1 file changed, 33 insertions(+), 2 deletions(-)
(limited to 'erts/doc/src')
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 94aff7c67b..13b72863f3 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -2526,7 +2526,7 @@ enif_map_iterator_destroy(env, &iter);
- int
+ enum ErlNifSelectReturn
enif_select(ErlNifEnv* env, ErlNifEvent event,
enum ErlNifSelectFlags mode, void* obj, Eterm ref)
@@ -2567,7 +2567,38 @@ 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.
- Returns 0 on success, or -1 if invalid arguments.
+ Returns an integer where different bits indicate the outcome of the call:
+
+ ERL_NIF_SELECT_ERROR
+ - The master error bit. It will always be set if the call failed for
+ any reason.
+ ERL_NIF_SELECT_STOP_CALLED
+ - 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.
+ ERL_NIF_SELECT_INVALID_EVENT
+ - Argument event is not a valid OS event object.
+ ERL_NIF_SELECT_FAILED
+ - The system call failed to add the event object to the poll set.
+
+ The return value from a successful call with mode as ERL_NIF_SELECT_STOP,
+ will contain either bit ERL_NIF_SELECT_STOP_CALLED or
+ ERL_NIF_SELECT_STOP_SCHEDULED.
+
+ Always use bitwise AND to test the return value. New significant bits
+ may be added in future releases to give more detailed information for both
+ failed and successful calls. Do NOT use equallity tests like ==, as
+ that may cause your application to stop working.
+ Example:
+
+retval = enif_select(env, fd, ERL_NIF_SELECT_READ, resource, ref);
+if (retval & ERL_NIF_SELECT_ERROR) {
+ /* handle error */
+}
+/* Success! */
+
+
--
cgit v1.2.3