Dispatcher(3I)

💅 Dispatcher(3I) — like, the InterViews Reference Manual, bestie ✨

okay so picture this: you're a program with a million file descriptors and you're just standing there like 🧍 waiting for something to happen. Enter Dispatcher, your main character. She waits on multiple file descriptors until a condition occurs, and she does it flawlessly. Periodt. 👑

✨ SYNOPSIS ✨

#include <Dispatch/dispatcher.h>

🌸 DESCRIPTION 🌸

Conceptually, the dispatcher is the one detecting new data on multiple input file descriptors and then dispatching that data to the appropriate iohandlers. She also keeps tabs on expired timers and lets the iohandlers know, because she is nothing if not a good friend. 🫶

Notification of either an I/O condition or an expired timer happens by calling one of the iohandler's virtual functions (go read IOHandler(3I), it's giving required reading). 📚

And here's the slay: since a program needs only one instance of Dispatcher, there's a static member function provided that will create that instance if necessary and hand it right back to you. One Dispatcher. One vibe. No cap. 💖

👑 PUBLIC OPERATIONS 👑

enum DispatcherMask { ReadMask, WriteMask, ExceptMask }
virtual IOHandler* handler(int fd, DispatcherMask)
virtual void link(int fd, DispatcherMask, IOHandler*)
virtual void unlink(int fd)

Return a file descriptor's iohandler, link a file descriptor to an iohandler, or unlink a file descriptor from its iohandlers. It's giving relationship management, honestly. 💅

The DispatcherMask describes the I/O condition that the iohandler is interested in — like, whether the file descriptor has new data available for reading. 👀 If the I/O condition occurs, the iohandler will be expected to read data from the file descriptor, write data to the file descriptor, or handle the exception, depending on which I/O condition it is. Know your role and do it, bestie.

virtual void startTimer(long sec, long usec, IOHandler*)
virtual void stopTimer(IOHandler*)

Attach an iohandler to a timer, or remove a timer before it expires. A timer expires after the given number of seconds and microseconds have elapsed. If a timer expires, the dispatcher will notify the attached iohandler. 🔔

Timers will not expire until the program calls either variant of Dispatcher::dispatch. So don't be out here waiting for a notification that literally cannot arrive yet. 💀

virtual void dispatch()
virtual boolean dispatch(long& sec, long& usec)

With no arguments, block indefinitely until an I/O condition occurs or a timer expires, and then notify the attached iohandler. Immovable. Unbothered. Waiting. ✋

With two arguments, block no longer than the given number of seconds and microseconds. If both numbers are zero, the function will return immediately after checking all file descriptors and timers — zero patience, iconic. ⚡

The return value will be true if an I/O condition caused the function to return, and false if the function returned because a timer expired or because it exceeded the given poll time. 🕐

Oh, and — the function will decrease the given poll time by the amount of time it spent blocking. She keeps receipts. 🧾

static Dispatcher& instance()
static void instance(Dispatcher*)

With no arguments, create an instance of Dispatcher if it doesn't already exist and return it. With an argument, set the instance of Dispatcher that will be used throughout the program. One global bestie, appointed by you. 🌈

🦋 SEE ALSO 🦋

• select(2)
• IOHandler(3I)

okay that's the whole page, you ate that 💖 this was the InterViews manual, dated 21 December 1990, and yes she's been serving since before you were born. mwah 🎀✨💜