Skip to content

Commit

Permalink
Merge pull request zeromq#3096 from sigiesec/add-poller-docs
Browse files Browse the repository at this point in the history
Add poller docs
  • Loading branch information
bluca authored May 14, 2018
2 parents 0a037a7 + 4fea718 commit 54aff77
Show file tree
Hide file tree
Showing 15 changed files with 314 additions and 8 deletions.
5 changes: 4 additions & 1 deletion doc/zmq.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
269 changes: 269 additions & 0 deletions doc/zmq_poller.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,269 @@
zmq_poller(3)
===========


NAME
----
zmq_poller - input/output multiplexing


SYNOPSIS
--------

*void *zmq_poller_new (void);*
*int zmq_poller_destroy (void **'poller_p');*

*int zmq_poller_add (void *'poller', void *'socket', void *'user_data', short 'events');
*int zmq_poller_modify (void *'poller', void *'socket', short 'events');*
*int zmq_poller_remove (void *'poller', void *'socket');*

*int zmq_poller_add_fd (void *'poller', int 'fd', void *'user_data', short 'events');*
*int zmq_poller_modify_fd (void *'poller', int 'fd', short 'events');*
*int zmq_poller_remove_fd (void *'poller', int 'fd');*

*int zmq_poller_wait_all (void *'poller',
zmq_poller_event_t *'events',
int 'n_events',
long 'timeout');*

DESCRIPTION
-----------
The _zmq_poller_*_ functions provide a mechanism for applications to multiplex
input/output events in a level-triggered fashion over a set of sockets.

_zmq_poller_new_ and _zmq_poller_destroy_ manage the lifetime of a poller
instance. _zmq_poller_new_ creates and returns a new poller instance, while
_zmq_poller_destroy_ destroys it. A pointer to a valid poller must be passed
as the _poller_p_ argument of _zmq_poller_destroy_. In particular,
_zmq_poller_destroy_ may not be called multiple times for the same poller
instance. _zmq_poller_destroy_ sets the passed pointer to NULL in case of a
successful execution. _zmq_poller_destroy_ implicitly unregisters all
registered sockets and file descriptors.

_zmq_poller_add_, _zmq_poller_modify_ and _zmq_poller_remove_ manage the 0MQ
sockets registered with a poller.

_zmq_poller_add_ registers a new _socket_ with a given _poller_. Both _poller_
and _socket_ must point to valid 0MQ objects. The _events_ parameter specifies
which event types the client wants to subscribe to. It is legal to specify no
events (i.e. 0), and activate them later with _zmq_poller_modify_.
In addition, _user_data_ may be specified, which is not used by the poller, but
passed back to the caller when an event was signalled in a call to
_zmq_poller_wait_ or _zmq_poller_wait_all_. _user_data_ may be NULL. If it is
not NULL, it must be a valid pointer. Otherwise, behaviour is undefined.
_zmq_poller_add_ may not be called multiple times for the same socket
(unless _zmq_poller_remove_ has been called for that socket).

_zmq_poller_modify_ modifies the subscribed events for a socket. It is
legal to specify no events (i.e. 0) to disable events temporarily, and
reactivate them later with another call to _zmq_poller_modify_.

_zmq_poller_remove_ removes a socket registration completely.
_zmq_poller_remove_ must be called before a socket is closed with _zmq_close_.

Note that it is not necessary to call _zmq_poller_remove_ for any socket
before calling _zmq_poller_destroy_.

Also note that calling _zmq_poller_remove_ is not equivalent to calling
_zmq_poller_modify_ with no events. _zmq_poller_modify_ does not free resources
associated with the socket registration, and requires that the _socket_
remains valid.

_zmq_poller_add_fd_, _zmq_poller_modify_fd_ and _zmq_poller_remove_fd_ are
analogous to the previous functions but manage regular file descriptiors
registered with a poller. On Windows, these functions can only be used with
WinSock sockets.

In the following, 0MQ sockets added with _zmq_poller_add_ and file descriptors
added with _zmq_poller_add_fd_ are referred to as 'registered objects'.

The *zmq_poller_event_t* structure is defined as follows:

["literal", subs="quotes"]
typedef struct
{
void *socket;
#if defined _WIN32
SOCKET fd;
#else
int fd;
#endif
void *user_data;
short events;
} zmq_poller_event_t;

For each registered object, _zmq_poller_wait_all()_ shall examine the
registered objects for the event(s) currently registered.

If none of the registered events have occurred, _zmq_poller_wait_all_ shall
wait 'timeout' milliseconds for an event to occur on any of the registered
objects. If the value of 'timeout' is `0`, _zmq_poller_wait_all_ shall
return immediately. If the value of 'timeout' is `-1`, _zmq_poller_wait_all_
shall block indefinitely until one event has occurred on any of the
registered objects.

The 'events' argument _zmq_poller_wait_all_ must be a pointer to an array of
at least 'n_events' elements. Behaviour is undefined if 'events' does not point
to an array of at least 'n_events' elements.

_zmq_poller_wait_all_ returns at most 'n_events' events. If more than
'n_events' events were signalled, only an unspecified subset of the signalled
events is returned through 'events'.

A caller is advised to ensure that 'n_events' is equal to the number of
registered objects. Otherwise, a livelock situation may result: If more than
'n_events' registered objects have an active event on each call to
_zmq_poller_wait_all_, it might happen that the same subset of registered
objects is always returned, and the caller never notices the events on the
others.

_zmq_poller_wait_all_ returns the number of valid elements. The valid elements
are placed in positions '0' to 'n_events - 1' in the 'events' array. All
members of a valid element are set to valid values by _zmq_poller_wait_all_.
The client does therefore not need to initialize the contents of the events
array before a call to _zmq_poller_wait_all_. It is unspecified whether the
the remaining elements of 'events' are written to by _zmq_poller_wait_all_.

EVENT TYPES
-----------

The 'events' parameter of _zmq_poller_add_ and _zmq_poller_modify_, and the
'events' member of the zmq_poller_event_t structure are bit masks constructed
by OR'ing a combination of the following event flags:

*ZMQ_POLLIN*::
For 0MQ sockets, at least one message may be received from the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLIN' flag of the
_poll()_ system call and generally means that at least one byte of data may be
read from 'fd' without blocking.

*ZMQ_POLLOUT*::
For 0MQ sockets, at least one message may be sent to the 'socket' without
blocking. For standard sockets this is equivalent to the 'POLLOUT' flag of the
_poll()_ system call and generally means that at least one byte of data may be
written to 'fd' without blocking.

*ZMQ_POLLERR*::
For 0MQ sockets this flag has no effect on the _zmq_poller_add_ and
_zmq_poller_modify_ functions, and is never set in the
'events' member of the zmq_poller_event_t structure.
For standard sockets, this flag is passed through _zmq_poller_wait_all_ to the
underlying _poll()_ system call and generally means that some sort of error
condition is present on the socket specified by 'fd'.

*ZMQ_POLLPRI*::
For 0MQ sockets this flag has no effect on the _zmq_poller_add_ and
_zmq_poller_modify_ functions, and is never set in the
'events' member of the zmq_poller_event_t structure.
For standard sockets this means there
is urgent data to read. Refer to the POLLPRI flag for more informations.
For a file descriptor, refer to your OS documentation: as an example, GPIO
interrupts are signaled through a POLLPRI event.
This flag has no effect on Windows.

NOTE: The _zmq_poller_*_ functions may be implemented or emulated using operating
system interfaces other than _poll()_, and as such may be subject to the limits
of those interfaces in ways not defined in this documentation.

THREAD SAFETY
-------------
Like most other 0MQ objects, a poller is not thread-safe. All operations must
be called from the same thread. Otherwise, behaviour is undefined.

RETURN VALUE
------------
_zmq_poller_new_ always returns a valid pointer to a poller.

All functions that return an int, return -1 in case of a failure. In that case,
zmq_errno() can be used to query the type of the error as described below.

_zmq_poller_wait_all_ returns the number of events signalled and returned in
the events array. It never returns 0.

All other functions return 0 in case of a successful execution.

ERRORS
------
On _zmq_poller_new_:
*ENOMEM*::
A new poller could not be allocated successfully.

On _zmq_poller_destroy_:
*EFAULT*::
_poller_p_ did not point to a valid poller. Note that passing an invalid pointer (e.g.
pointer to deallocated memory) may cause undefined behaviour (e.g. an access violation).

On _zmq_poller_add_, _zmq_poller_modify_ and _zmq_poller_remove_:
*EFAULT*::
_poller_ did not point to a valid poller. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).
*ENOTSOCK*::
_socket_ did not point to a valid socket. Note that passing an
invalid pointer (e.g. pointer to deallocated memory) may cause undefined
behaviour (e.g. an access violation).

On _zmq_poller_add_:
*EMFILE*::
TODO

On _zmq_poller_add_ or _zmq_poller_add_fd_:
*ENOMEM*::
Necessary resources could not be allocated.
*EINVAL*::
_socket_ resp. _fd_ was already registered with the poller.

On _zmq_poller_modify_, _zmq_poller_modify_fd_, _zmq_poller_remove_ or
_zmq_poller_remove_fd_:
*EINVAL*::
_socket_ resp. _fd_ was not registered with the poller.

On _zmq_poller_add_fd_, _zmq_poller_modify_fd_ and _zmq_poller_remove_fd_:
*EBADF**:
The _fd_ specified was the retired fd.

On _zmq_poller_wait_ and _zmq_poller_wait_all_:
*ETERM*::
At least one of the registered objects is a 'socket' whose associated 0MQ
'context' was terminated.
*EFAULT*::
The provided 'events' was NULL, or 'poller' did not point to a valid poller,
or there are no registered objects and 'timeout' was negative.
*EINTR*::
The operation was interrupted by delivery of a signal before any events were
available.
*EAGAIN*::
No registered event was signalled before the timeout was reached.


EXAMPLE
-------
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
----
void *poller = zmq_poller_new ();

zmq_poller_event_t events [2];
/* First item refers to 0MQ socket 'socket' */
zmq_poller_add (poller, socket, ZMQ_POLLIN, NULL);
/* Second item refers to standard socket 'fd' */
zmq_poller_add_fd (poller, fd, ZMQ_POLLIN, NULL);
/* Poll for events indefinitely */
int rc = zmq_poller_wait_all (items, events, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in 'events' */
zmq_poller_destroy (&poller);
----


SEE ALSO
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]


AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.
1 change: 1 addition & 0 deletions doc/zmq_poller_add.txt
1 change: 1 addition & 0 deletions doc/zmq_poller_add_fd.txt
1 change: 1 addition & 0 deletions doc/zmq_poller_destroy.txt
1 change: 1 addition & 0 deletions doc/zmq_poller_modify.txt
1 change: 1 addition & 0 deletions doc/zmq_poller_modify_fd.txt
1 change: 1 addition & 0 deletions doc/zmq_poller_new.txt
1 change: 1 addition & 0 deletions doc/zmq_poller_remove.txt
1 change: 1 addition & 0 deletions doc/zmq_poller_remove_fd.txt
1 change: 1 addition & 0 deletions doc/zmq_poller_wait_all.txt
2 changes: 1 addition & 1 deletion doc/zmq_setsockopt.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 14 additions & 2 deletions src/socket_poller.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,13 @@ int zmq::socket_poller_t::add (socket_base_t *socket_,
-1
#endif
};
items.push_back (item);
try {
items.push_back (item);
}
catch (const std::bad_alloc &) {
errno = ENOMEM;
return -1;
}
need_rebuild = true;

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

return 0;
Expand Down
5 changes: 3 additions & 2 deletions src/zmq.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down Expand Up @@ -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 ()) {
Expand Down
Loading

0 comments on commit 54aff77

Please sign in to comment.