Merge pull request #3096 from sigiesec/add-poller-docs

Add poller docs

doc/zmq.txt

@@ -142,7 +142,10 @@ Monitoring socket events::
 0MQ provides a mechanism for applications to multiplex input/output events over
 a set containing both 0MQ sockets and standard sockets. This mechanism mirrors
 the standard _poll()_ system call, and is described in detail in
-linkzmq:zmq_poll[3].
+linkzmq:zmq_poll[3]. This API is deprecated, however.
+
+There is a new DRAFT API with multiple zmq_poller_* function, which is described
+in linkzmq:zmq_poller[3].
 
 
 Transports

doc/zmq_poller_add.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_poller_add_fd.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_poller_destroy.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_poller_modify.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_poller_modify_fd.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_poller_new.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_poller_remove.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_poller_remove_fd.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_poller_wait_all.txt

+zmq_poller.txt
\ No newline at end of file

doc/zmq_setsockopt.txt

@@ -774,7 +774,7 @@ up.
 When ZMQ_ROUTER_MANDATORY is set to `1`, 'ZMQ_POLLOUT' events will be generated
 if one or more messages can be sent to at least one of the peers. If
 ZMQ_ROUTER_MANDATORY is set to `0`, the socket will generate a 'ZMQ_POLLOUT'
-event on every call to 'zmq_poll'.
+event on every call to 'zmq_poll' resp. 'zmq_poller_wait_all'.
 
 [horizontal]
 Option value type:: int

src/socket_poller.cpp

@@ -137,7 +137,13 @@ int zmq::socket_poller_t::add (socket_base_t *socket_,
         -1
 #endif
     };
+    try {
         items.push_back (item);
+    }
+    catch (const std::bad_alloc &) {
+        errno = ENOMEM;
+        return -1;
+    }
     need_rebuild = true;
 
     return 0;
@@ -162,7 +168,13 @@ int zmq::socket_poller_t::add_fd (fd_t fd_, void *user_data_, short events_)
         -1
 #endif
     };
+    try {
         items.push_back (item);
+    }
+    catch (const std::bad_alloc &) {
+        errno = ENOMEM;
+        return -1;
+    }
     need_rebuild = true;
 
     return 0;

src/zmq.cpp

@@ -1167,7 +1167,9 @@ int zmq_poll (zmq_pollitem_t *items_, int nitems_, long timeout_)
 void *zmq_poller_new (void)
 {
     zmq::socket_poller_t *poller = new (std::nothrow) zmq::socket_poller_t;
-    alloc_assert (poller);
+    if (!poller) {
+        errno = ENOMEM;
+    }
     return poller;
 }
 
@@ -1295,7 +1297,6 @@ int zmq_poller_remove_fd (void *poller_, int fd_)
     return ((zmq::socket_poller_t *) poller_)->remove_fd (fd_);
 }
 
-
 int zmq_poller_wait (void *poller_, zmq_poller_event_t *event_, long timeout_)
 {
     if (!poller_ || !((zmq::socket_poller_t *) poller_)->check_tag ()) {

tests/test_poller.cpp

@@ -339,9 +339,19 @@ void call_poller_modify_unregistered_fails (void *poller, void *socket)
 
 void call_poller_add_no_events (void *poller, void *socket)
 {
-    //  add a socket with no events
-    //  TODO should this really be legal? it does not make any sense...
+    //  add a socket with no events initially (may be activated later with
+    //  zmq_poller_modify)
     TEST_ASSERT_SUCCESS_ERRNO (zmq_poller_add (poller, socket, NULL, 0));
+    //  TODO test that no events are signalled
+}
+
+void call_poller_modify_no_events (void *poller, void *socket)
+{
+    //  deactivates all events for a socket temporarily (may be activated again
+    //  later with zmq_poller_modify)
+    zmq_poller_add (poller, socket, NULL, ZMQ_POLLIN);
+    TEST_ASSERT_SUCCESS_ERRNO (zmq_poller_modify (poller, socket, 0));
+    //  TODO test that no events are signalled
 }
 
 void call_poller_add_fd_twice_fails (void *poller, void * /*zeromq_socket*/)
@@ -389,6 +399,7 @@ TEST_CASE_FUNC_PARAM (call_poller_remove_unregistered_fails,
 TEST_CASE_FUNC_PARAM (call_poller_modify_unregistered_fails,
                       test_with_empty_poller)
 TEST_CASE_FUNC_PARAM (call_poller_add_no_events, test_with_empty_poller)
+TEST_CASE_FUNC_PARAM (call_poller_modify_no_events, test_with_empty_poller)
 TEST_CASE_FUNC_PARAM (call_poller_add_fd_twice_fails, test_with_empty_poller)
 TEST_CASE_FUNC_PARAM (call_poller_remove_fd_unregistered_fails,
                       test_with_empty_poller)
@@ -603,6 +614,7 @@ int main (void)
     RUN_TEST (test_call_poller_remove_unregistered_fails);
     RUN_TEST (test_call_poller_modify_unregistered_fails);
     RUN_TEST (test_call_poller_add_no_events);
+    RUN_TEST (test_call_poller_modify_no_events);
     RUN_TEST (test_call_poller_add_fd_twice_fails);
     RUN_TEST (test_call_poller_remove_fd_unregistered_fails);
     RUN_TEST (test_call_poller_modify_fd_unregistered_fails);