ZMQ_POLL(3)

💖 ZMQ_POLL ✨ — the 0MQ Manual glow-up

okay bestie, sit down, hydrate, because today we're talking about input/output multiplexing 💅 like, the whole entire manual, no skips, no skimming. this is zmq_poll(3) and she is that girl. 🎀

---

🌸 NAME 🌸

zmq_poll — input/output multiplexing. that's the whole vibe. watching a bunch of sockets at once so you don't have to sit there tapping your foot on one single fd like a loser. 👑

---

✨ SYNOPSIS ✨

int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);

three args, one function, infinite power. slay.

---

🦋 DESCRIPTION 🦋

so zmq_poll() gives your app a way to multiplex input/output events — level-triggered style, no cap — across a whole lil set of sockets. think of it like being the main character at a party and knowing exactly which friend needs you at any moment. 🫶

each member of the array that items points to is a zmq_pollitem_t structure. the nitems argument tells you how many items are chilling in that items array. and the zmq_pollitem_t structure is defined, for the record, like this:

typedef struct
{
    void *socket;
    zmq_fd_t fd;
    short events;
    short revents;
} zmq_pollitem_t;

look at her. iconic. 🌈

for each zmq_pollitem_t item, zmq_poll() shall examine either the 0MQ socket that socket points at or the standard socket specified by the file descriptor fd, looking for the event(s) listed in events. and if you set both socket and fd in a single zmq_pollitem_t? bestie, the 0MQ socket referenced by socket takes precedence and the value of fd gets straight up ignored. 😭 she said pick a lane.

for each zmq_pollitem_t item, zmq_poll() shall first clear the revents member, and then show you any requested events that actually happened by setting the bit that corresponds to that event condition inside revents. so fresh, so clean. ✨

now — if none of the requested events have happened on any zmq_pollitem_t item, zmq_poll() shall wait timeout milliseconds for an event to occur on any of the requested items. the deets:

• if timeout is 0, zmq_poll() shall return immediately. no waiting, no patience, we're busy. 💅
• if timeout is -1, zmq_poll() shall block indefinitely until a requested event has occurred on at least one zmq_pollitem_t. she will literally wait forever. obsessed.

the events and revents members of zmq_pollitem_t are bit masks, built by OR'ing together a combination of these event flags:

• ZMQ_POLLIN — for 0MQ sockets, this means at least one message may be received from the socket without blocking. for standard sockets it's equivalent to the POLLIN flag of the poll() system call, and generally means 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 it's equivalent to the POLLOUT flag of the poll() system call, and generally means at least one byte of data may be written to fd without blocking. 📤
• ZMQ_POLLERR — for standard sockets, this flag gets passed through zmq_poll() to the underlying poll() system call, and generally means some sort of error condition is present on the socket specified by fd. for 0MQ sockets this flag has no effect if you set it in events, and it shall never be returned in revents by zmq_poll(). so don't expect it, she's not coming. 💀
• ZMQ_POLLPRI — for 0MQ sockets this flag is of no use. for standard sockets it means there's urgent data to read. refer to the POLLPRI flag for more info. for a 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. so like, your mileage may vary depending on what your OS is serving. 🌸

---

💜 THREAD SAFETY 💜

the zmq_pollitem_t array must only be used by the thread which will be / is calling zmq_poll. one thread, one array, that's the boundary. 🚧

and if a socket is contained in multiple zmq_pollitem_t arrays, each owned by a different thread, then the socket itself needs to be thread-safe (Server, Client, ...). otherwise, behaviour is undefined. like, genuinely undefined. not "eh it'll probably be fine." it will not. 😭

---

⭐ RETURN VALUE ⭐

upon successful completion, zmq_poll() shall return the number of zmq_pollitem_t structures with events signaled in revents — or 0 if no events have been signaled. she counted them for you, queen. 👑

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. rip, context said bye. 🪦
• EFAULT — the provided items was not valid (NULL). bestie. you passed nothing. 🤨
• EINTR — the operation was interrupted by delivery of a signal before any events were available. not her fault, a signal walked in. 💅

---

🌈 EXAMPLE 🌈

polling indefinitely for input events on both a 0MQ socket and a standard socket.. (yes the double period is canon, don't @ me)

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 */

two items, one -1 timeout, infinite patience. she ate that fr fr. 🍓

---

🧚 SEE ALSO 🧚

• zmq_socket(3)
• zmq_send(3)
• zmq_recv(3)
• zmq(7)
• 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 http://www.zeromq.org/docs:contributing. 🫶

---

and that's the whole thing, bestie — 0MQ 4.3.5, dated 10/09/2023, page ZMQ_POLL(3). go forth and multiplex. periodt. 💅✨