mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-25 22:30:51 +08:00
136 lines
4.9 KiB
Plaintext
136 lines
4.9 KiB
Plaintext
= zmq_poll(3)
|
|
|
|
|
|
== NAME
|
|
zmq_poll - input/output multiplexing
|
|
|
|
|
|
== SYNOPSIS
|
|
|
|
*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
|
|
|
|
|
|
== DESCRIPTION
|
|
The _zmq_poll()_ function provides a mechanism for applications to multiplex
|
|
input/output events in a level-triggered fashion over a set of sockets. Each
|
|
member of the array pointed to by the 'items' argument is a *zmq_pollitem_t*
|
|
structure. The 'nitems' argument specifies the number of items in the 'items'
|
|
array. The *zmq_pollitem_t* structure is defined as follows:
|
|
|
|
["literal", subs="quotes"]
|
|
typedef struct
|
|
{
|
|
void '*socket';
|
|
zmq_fd_t 'fd';
|
|
short 'events';
|
|
short 'revents';
|
|
} zmq_pollitem_t;
|
|
|
|
For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ
|
|
socket referenced by 'socket' *or* the standard socket specified by the file
|
|
descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and
|
|
'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by
|
|
'socket' shall take precedence and the value of 'fd' shall be ignored.
|
|
|
|
For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents'
|
|
member, and then indicate any requested events that have occurred by setting the
|
|
bit corresponding to the event condition in the 'revents' member.
|
|
|
|
If none of the requested events have occurred on any *zmq_pollitem_t* item,
|
|
_zmq_poll()_ shall wait 'timeout' milliseconds for an event to occur on
|
|
any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_
|
|
shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall
|
|
block indefinitely until a requested event has occurred on at least one
|
|
*zmq_pollitem_t*.
|
|
|
|
The 'events' and 'revents' members of *zmq_pollitem_t* 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 standard sockets, this flag is passed through _zmq_poll()_ to the
|
|
underlying _poll()_ system call and generally means that some sort of error
|
|
condition is present on the socket specified by 'fd'. For 0MQ sockets this flag
|
|
has no effect if set in 'events', and shall never be returned in 'revents' by
|
|
_zmq_poll()_.
|
|
|
|
*ZMQ_POLLPRI*::
|
|
For 0MQ sockets this flags is of no use. For standard sockets this means there
|
|
is urgent data to read. Refer to the POLLPRI flag for more information.
|
|
For file descriptor, refer to your use case: as an example, GPIO interrupts
|
|
are signaled through a POLLPRI event.
|
|
This flag has no effect on Windows.
|
|
|
|
NOTE: The _zmq_poll()_ function 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
|
|
The *zmq_pollitem_t* array must only be used by the thread which
|
|
will/is calling _zmq_poll_.
|
|
|
|
If a socket is contained in multiple *zmq_pollitem_t* arrays, each owned by a
|
|
different thread, the socket itself needs to be thread-safe (Server, Client, ...).
|
|
Otherwise, behaviour is undefined.
|
|
|
|
|
|
== RETURN VALUE
|
|
Upon successful completion, the _zmq_poll()_ function shall return the number
|
|
of *zmq_pollitem_t* structures with events signaled in 'revents' or `0` if no
|
|
events have been signaled. Upon failure, _zmq_poll()_ shall return `-1` and set
|
|
'errno' to one of the values defined below.
|
|
|
|
|
|
== ERRORS
|
|
*ETERM*::
|
|
At least one of the members of the 'items' array refers to a 'socket' whose
|
|
associated 0MQ 'context' was terminated.
|
|
*EFAULT*::
|
|
The provided 'items' was not valid (NULL).
|
|
*EINTR*::
|
|
The operation was interrupted by delivery of a signal before any events were
|
|
available.
|
|
|
|
|
|
== EXAMPLE
|
|
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
|
|
----
|
|
zmq_pollitem_t items [2];
|
|
/* First item refers to 0MQ socket 'socket' */
|
|
items[0].socket = socket;
|
|
items[0].events = ZMQ_POLLIN;
|
|
/* Second item refers to standard socket 'fd' */
|
|
items[1].socket = NULL;
|
|
items[1].fd = fd;
|
|
items[1].events = ZMQ_POLLIN;
|
|
/* Poll for events indefinitely */
|
|
int rc = zmq_poll (items, 2, -1);
|
|
assert (rc >= 0);
|
|
/* Returned events will be stored in items[].revents */
|
|
----
|
|
|
|
|
|
== SEE ALSO
|
|
* xref:zmq_socket.adoc[zmq_socket]
|
|
* xref:zmq_send.adoc[zmq_send]
|
|
* xref:zmq_recv.adoc[zmq_recv]
|
|
* xref:zmq.adoc[zmq]
|
|
|
|
Your operating system documentation for the _poll()_ system call.
|
|
|
|
|
|
== AUTHORS
|
|
This page was written by the 0MQ community. To make a change please
|
|
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.
|