rpoll(3)

okay bestie, meet rpoll(3) — the callback-forward little library that makes watching file descriptors and timers feel less like a group project where nobody communicates. It’s giving event-driven main character energy, and every fact below is staying exactly where it belongs. 💅

✨ NAME ✨

rpoll — callback functions for file descriptors and timers 🌸

🦋 SYNOPSIS 🦋

here’s the whole signature stack, no cap:

# include <rpoll.h>

typedef void (*poll_f)(int fd, int mask, void *arg);
typedef void (*timer_f)(int tid, void *arg);

int poll_register(int fd, poll_f func, void *arg, int mask);

void poll_unregister(int handle);

int poll_start_timer(u_int msecs, int repeat, timer_f func,
            void *arg);

void poll_stop_timer(int handle);

int poll_start_utimer(unsigned long long usecs, int repeat,
            timer_f func, void *arg);

void poll_dispatch(int wait);

💅 DESCRIPTION 💅

so many programs need to read from several file descriptors at the same time — multitasking queen behavior, honestly. Usually they reach for select(3c) or poll(2). But those calls are lowkey clumsy to use, and using one of them is probably not portable to other systems, because not all systems support both calls. 😭

The rpoll(l) family is designed to overcome those restrictions. (Yes, the original says rpoll(l) there, and I’m not gonna gaslight you about it.) They support the well-known and understood technique of event-driven programing — again, original spelling, love that for us — and on top of select(3c) and poll(2) they also support timers. 🕰️✨

Every event on a file descriptor or every timer event gets translated into a call to a user-defined callback function. Those functions need to be registered. A file descriptor is registered with poll_register. fd is the file descriptor to watch, and mask is an event mask. It may be any combination of:

• POLL_IN — get informed when input on the file descriptor is possible,
• POLL_OUT — get informed when output is possible,
• POLL_EXCEPT — get informed when an exceptional condition occures. An example of an exceptional condition is the arrival of urgent data. (Note that an end of file condition is signaled via POLL_IN.) 🫶

func is the user function to be called, and arg is a user-supplied argument for this function. The callback functions are called with the file descriptor, a mask describing the actual events (from the set supplied in the registration), and the user argument. poll_register returns a handle, which may be used later to de-register the file descriptor. A file descriptor may be registered more than once if the function, the user arguments, or both differ in the call to poll_register. If func and arg are the same, then no new registration is done; instead, the event mask of the registration is changed to reflect the new mask. 🔁

A registered file descriptor may be de-registered by calling poll_unregister with the handle returned by poll_register. 💖

A timer is created with poll_start_timer or poll_start_utimer. In poll_start_timer, msecs is the number of milliseconds; in poll_start_utimer, usecs is the number of microseconds — that’s the delay after which the timer event will be generated. If the functions use the poll(2) system call, then usecs is rounded to milliseconds and poll_start_timer is called. (Microsecond girlies, know your conversion.) repeat selects one-short behavior if 0 or a repeatable timer if not 0. A one-short timer will automatically unregistered after expiry — original grammar, we move. func is the user function which will be called with a timer id and the user-supplied arg. poll_start_timer and poll_start_utimer return a timer id, which may be used to cancel the timer with poll_stop_timer. A one-short timer should be canceled only if it has not yet fired. ⏳

poll_dispatch must be called to actually dispatch events. wait is a flag, which should be 0 if only a poll should be done. In this case, the function returns after polling the registered file descriptors and timers. If wait is not 0, poll_dispatch waits until an event occures. All events are dispatch (i.e. callback functions called) and poll_dispatch returns. 🚀

Typical use is:

while(1)
     poll_dispatch(1);

🌈 SEE ALSO 🌈

poll(2), select(3C) — go read those too, bestie. 📚

💖 RETURN VALUES 💖

poll_register, poll_start_timer, and poll_start_utimer return a handle which may be used to unregister the file descriptor or cancel the timer.

Both functions and poll_dispatch call xrealloc(l) and can end in panic(l). 💀

🛑 ERRORS 🛑

System call or memory allocation errors are fatal and are handle by calling panic(l). The one exception is a return of EINTR from select(3c) or poll(2) in poll_dispatch. In this case poll_dispatch simply returns. 🛑

💀 BUGS 💀

Obscure sequences of poll_start_timer and poll_stop_timer in callback functions may probably break the code. 😬

The semantics of POLL_EXCEPT are not clear. 🙈

👑 AUTHORS 👑

Hartmut Brandt, harti@freebsd.org — iconic. 👑

---

source/version check: this page is from the BEGEMOT Library (footer tag: BEGEMOT), dated 8 Dec 2006. periodt. 💖