ZMQ_POLLER(3)

💅 ZMQ_POLLER(3) — the 0MQ Manual, but make it cute ✨

okay bestie, sit down, grab a strawberry 🍓, because we're about to talk about zmq_poller — aka the function family that does input/output multiplexing. it's in the 0MQ Manual, section 3, and it's genuinely iconic, no cap.

---

✨ NAME ✨

zmq_poller — input/output multiplexing 💖

---

🦋 SYNOPSIS 🦋

here's the whole lineup, exactly as it comes, don't @ me:

void *zmq_poller_new (void);

int zmq_poller_destroy (void **poller_p);

int zmq_poller_size (void *poller);

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 (void *poller, zmq_poller_event_t *event, long
timeout);

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

int zmq_poller_fd (void *poller, zmq_fd_t *fd);

---

🌸 DESCRIPTION 🌸

the zmq_poller*_ functions are literally the friend group that lets your app multiplex input/output events across a whole set of sockets — and they do it in a level-triggered fashion. that's the vibe. ✨

🎀 making and unmaking a poller

zmq_poller_new and zmq_poller_destroy manage the lifetime of a poller instance. zmq_poller_new creates and returns a shiny 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. and listen — zmq_poller_destroy may not be called multiple times for the same poller instance, that's giving chaos energy and we don't do that 🙈. on a successful execution, zmq_poller_destroy sets the passed pointer to NULL. also, zmq_poller_destroy implicitly unregisters all registered sockets and file descriptors. it cleans up after itself, we love a tidy queen 👑

🔢 how many things are we watching

zmq_poller_size queries the number of sockets or file descriptors registered with a poller. the initial size of a poller is 0, a successful add operation increases the size by 1, and a successful remove operation decreases the size by 1. the size is unaffected by the events specified — events don't get a vote here 💅

🧚 socket registration, the main character arc

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. 🫠 you must only add a socket to a single poller instance once (unless zmq_poller_remove has been called for that socket before). you may add a socket to multiple poller instances, if the socket itself is explicitly thread-safe (Server, Client, ...). if the socket is not, you may invoke undefined behavior. so like… read the room, bestie.
• 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. very pause-and-resume of it 🌈
• zmq_poller_remove removes a socket registration completely. zmq_poller_remove must be called before a socket is closed with zmq_close. periodt.

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. they are not the same girl, don't confuse them 💀

🍓 file descriptors, the crossover episode

zmq_poller_add_fd, zmq_poller_modify_fd and zmq_poller_remove_fd are analogous to the previous functions, but they manage regular file descriptors registered with a poller. on Windows, these functions can only be used with WinSock sockets. iykyk 🪟

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 event struct, she's famous

the zmq_poller_event_t structure is defined as follows:

typedef struct
{
    void *socket;
    zmq_fd_t fd;
    void *user_data;
    short events;
} zmq_poller_event_t;

👑 waiting, the whole point

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. so -1 is giving "i'll wait forever, i'm loyal" 😭

the events argument of 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. not a vibe, please don't.

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. 😵 the number of objects registered can be queried with zmq_poller_size.

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. for socket events, socket is non-null and fd is an operating system specific value for an invalid socket (-1 or INVALID_SOCKET). for fd events, socket is NULL and fd is a valid file descriptor. the client does therefore not need to initialize the contents of the events array before a call to zmq_poller_wait_all — so no need to pre-game the array, she comes ready ✨. it is unspecified whether the the remaining elements of events are written to by zmq_poller_wait_all. (yes, the original says "the the". we're keeping it. it's part of the lore now 💜)

🦋 asking for the fd

zmq_poller_fd queries the file descriptor associated with the zmq_poller, and stores it in the address pointer to by fd. the zmq_poller is only guaranteed to have a file descriptor if at least one thread-safe socket is currently registered.

note that closing a socket that is registered in a poller leads to undefined behavior. the socket must be unregistered first. 🚨

---

💅 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. mix and match, it's a build-your-own-adventure 🌈

• 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 information. 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. so like, she's adaptable, but also slightly unpredictable. main character energy tbh 🧚

---

🫶 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. one poller, one thread, that's the rule 💅

in addition to that, if you want to add a socket to multiple existing poller instances, the socket itself needs to be thread-safe (Server, Client, ...). otherwise, behaviour is undefined. no cap.

---

⭐ RETURN VALUE ⭐

• zmq_poller_new returns a valid pointer to a poller, or NULL in case of a failure.
• 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. she always has something to say ✨
• all other functions return 0 in case of a successful execution.

---

...and that's part 1, bestie — more is coming, don't go anywhere 💖

💥 ERRORS 💥

okay bestie, when things go sideways, these are the error codes you might catch. vibe check each one. No cap.

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_size:

• 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).

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:

• ENOMEM — Necessary resources could not be allocated. 😭
• 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 or all event subscriptions are disabled 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. ⏳

On zmq_poller_fd:

• EINVAL — The poller has no associated file descriptor. 🤷‍♀️
• EFAULT — The provided poller did not point to a valid poller. 💔

---

✨ EXAMPLE ✨

okay so imagine we're polling indefinitely for input events on both a 0MQ socket and a standard socket.. slay

void *poller = zmq_poller_new ();

/* First item refers to 0MQ socket 'socket' */
zmq_poller_add (poller, socket, NULL, ZMQ_POLLIN);
/* Second item refers to standard socket 'fd' */
zmq_poller_add_fd (poller, fd, NULL, ZMQ_POLLIN);

zmq_poller_event_t events [2];
/* Poll for events indefinitely */
int rc = zmq_poller_wait_all (poller, events, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in 'events' */
for (int i = 0; i < 2; ++i) {
    if (events[i].socket == socket && events[i].events & ZMQ_POLLIN) {
        // ...
    } else if (events[i].fd == fd && events[i].events & ZMQ_POLLIN)) {
        // ...
    }
}
zmq_poller_destroy (&poller);

---

👀 SEE ALSO 👀

• zmq_socket(3)
• zmq_send(3)
• zmq_recv(3)
• 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. 💖

---

and that's the whole tea, bestie — this page is from 0MQ 4.3.5, dated 10/09/2023, and it's the ZMQ_POLLER(3) manual. periodt 💅✨