ZMQ_POLL(3)

🌸 ZMQ_PPOLL 💅

okay bestie, this is the 0MQ Manual page for zmq_ppoll — input/output multiplexing with signal mask. yes it's a mouthful, no you don't have to be scared. sit down, drink some water, let's get into it 🫶

---

✨ NAME ✨

zmq_ppoll — input/output multiplexing with signal mask 🌈

---

🎀 SYNOPSIS 🎀

int zmq_ppoll (zmq_pollitem_t *items, int nitems, long timeout, const
       sigset_t *sigmask);

---

💖 DESCRIPTION 💖

okay so the way that zmq_poll() and zmq_ppoll() relate to each other is literally the same energy as poll(2) vs ppoll(2), and select(2) vs pselect(2). like, same family, one of them just has extra coping mechanisms. what zmq_ppoll() gives you is that an application can safely wait until either a file descriptor becomes ready or until a signal is caught. best of both worlds, no cap. 💅

if you call zmq_ppoll() with sigmask set to NULL, its behavior is identical to that of zmq_poll(). go read zmq_poll(3) if you want the tea on that one.

to make full use of zmq_ppoll(), you gotta construct a non-NULL pointer to a signal mask and pass it to sigmask. check sigprocmask(2) for more deets on that. when you do this, inside the actual ppoll() (or pselect(), see the note below) system call, an atomic operation happens, and it's three steps:

1. The current signal mask is replaced by the one pointed to by sigmask.
2. The actual poll() call is done.
3. The original signal mask is restored.

the way that these operations are done atomically means there is no opportunity for race conditions in between the calls changing the signal mask and the poll/select system call. none. zero. not on my watch. 🙈

what that means is that only during this (atomic) call can we unblock certain signals, so that they can be handled at that time only, not outside of the call. so effectively, we extend our poller into a function that not only watches sockets for changes, but also watches the "POSIX signal socket" for incoming signals. at other times, these signals will be blocked, and we will not have to deal with interruptions in system calls at these other times. iconic behavior honestly 👑

Note The zmq_ppoll() function may be implemented or emulated using operating system interfaces other than ppoll(), and as such may be subject to the limits of those interfaces in ways not defined in this documentation.

Note There is no ppoll or pselect on Windows, so zmq_ppoll() is not supported in Windows builds. It is still callable, but its sigmask has void pointer type (because sigset_t is also not available on Windows) and zmq_ppoll() will return with an error (see error section below). not it being callable but refusing to work 💀

---

🧵 THREAD SAFETY 🧵

the zmq_pollitem_t array must only be used by the thread which will/is calling zmq_ppoll. no sharing, no passing it around like a group chat screenshot. 🙅

if a socket is contained in multiple zmq_pollitem_t arrays, each owned by a different thread, the socket itself needs to be thead-safe (Server, Client, ...). otherwise, behaviour is undefined. and undefined behavior is not the vibe. 😭

---

⭐ RETURN VALUE ⭐

upon successful completion, the zmq_ppoll() function shall return the number of zmq_pollitem_t structures with events signaled in revents or 0 if no events have been signaled. slay. ✨

upon failure, zmq_ppoll() shall return -1 and set errno to one of the values defined below. that's the sad path bestie 💔

---

🦋 ERRORS 🦋

• ETERM — at least one of the members of the items array refers to a socket whose associated 0MQ context was terminated. rip to that context 🪦
• EFAULT — the provided items was not valid (NULL).
• EINTR — the operation was interrupted by delivery of a signal before any events were available.
• EINTR — the operation was interrupted by delivery of a signal before any events were available.
• ENOTSUP — zmq_ppoll() was not activated in this build.

yes, EINTR is listed twice. no, that's not a typo i made, that's just how the page is. we keep it. fr fr 🫶

---

🔥 EXAMPLE 🔥

polling indefinitely for input events on both a 0MQ socket and a standard socket. see the example section of zmq_poll(3). one only needs to replace the zmq_poll call with zmq_ppoll and add a NULL argument for the sigmask parameter. easy.

handle SIGTERM during zmq_ppoll (and block it otherwise)..

// simple global signal handler for SIGTERM
static bool sigterm_received = false;
void handle_sigterm (int signum) {
    sigterm_received = true;
}

// set up signal mask and install handler for SIGTERM
sigset_t sigmask, sigmask_without_sigterm;
sigemptyset(&sigmask);
sigaddset(&sigmask, SIGTERM);
sigprocmask(SIG_BLOCK, &sigmask, &sigmask_without_sigterm);
struct sigaction sa;
memset(&sa, '\0', sizeof(sa));
sa.sa_handler = handle_sigterm;

// poll
zmq_pollitem_t items [1];
// Just one item, which refers to 0MQ socket 'socket' */
items[0].socket = socket;
items[0].events = ZMQ_POLLIN;
// Poll for events indefinitely, but also exit on SIGTERM
int rc = zmq_poll (items, 2, -1, &sigmask_without_sigterm);
if (rc < 0 && errno == EINTR && sigterm_received) {
  // do your SIGTERM business
} else {
  // do your non-SIGTERM error handling
}

---

👀 SEE ALSO 👀

zmq_poll(3) 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. community-written, community-loved, we love to see it 💜

---

and that's the whole page bestie, you ate it 🍓 this was 0MQ 4.3.5, dated 10/09/2023, and it's the ZMQ_POLL(3) page — go forth and multiplex responsibly 🧚✨💖