FBB::Selector(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

💖 FBB::Selector(3bobcat) — Timed Delays, Multiple File I/O 💖

okay bestie, pull up a chair, we're doing the bobcat manual pages and this one is genuinely a bop. it's FBB::Selector, from the 3bobcat manual, and it's giving "I control time AND your file descriptors." iconic behaviour, honestly.

✨ NAME ✨

FBB::Selector — Timed delays, Alarms and Multiple File I/O. 🎀

✨ SYNOPSIS ✨

#include <bobcat/selector>
Linking option: -lbobcat

✨ DESCRIPTION ✨

so like. FBB::Selector objects are wrappers around the select(2) system calls, and they let you do timed delays, alarm functionality, and/or multiple file I/O. slay.

the one catch: it needs file descriptors, and file descriptors are not an official part of C++. like, they're just not in the C++ syllabus. but most operating systems literally offer them, so we're fine. and sockets? sockets are well-known file descriptors. iykyk. 💅

✨ NAMESPACE ✨

FBB

all constructors, members, operators and manipulators mentioned in this man-page are defined in the namespace FBB. periodt.

✨ INHERITS FROM ✨

-

(nothing bestie, it stands on its own two feet 👑)

✨ CONSTRUCTORS ✨

  • Selector() — this constructor initializes the object. that's it, that's the job. 💖

also, copy and move constructors (and assignment operators) are available. so you can copy it, move it, whatever your heart desires.

✨ MEMBER FUNCTIONS ✨

  • void addExceptFd(int fd) — adds a file descriptor to the set of file descriptors that are monitored for exceptions. and no, bestie, these are not C++ exceptions — don't get it twisted. see man 2 select for the details. 🙈
  • void addReadFd(int fd) — adds a file descriptor to the set of file descriptors that are monitored for reading. yes, reading. we love a reader. 📖
  • void addWriteFd(int fd) — adds a file descriptor to the set of file descriptors that are monitored for writing. ✍️
  • int exceptFd() — returns -1 if no more file descriptors are available in the exception category. otherwise it returns the next available file descriptor in the exception category. once you return from wait, you can call this repeatedly until -1 comes back, servicing each available file descriptor in turn. it's a little assembly line, and it ate. 🔥
  • void noAlarm() — this member prevents any timeout-alarm from occurring. bye bye alarm. 🧚
  • int nReady() — returns the number of available file descriptors. returns 0 at a timeout, and returns -1 when select(2) itself failed. (not me noticing the original says "-1: is returned" — yes bestie, there's a lil colon typo in the source, we keep it real.) 💀
  • int readFd() — returns -1 if no more file descriptors are available for reading. otherwise it returns the next available file descriptor for reading. once you return from wait, you can call this repeatedly until -1 comes back, servicing each available file descriptor in turn.

now listen: the file whose file descriptor is returned by readFd may also be at its end-of-file position. the file is ready for reading, but no characters will be returned when you try to read from it, because of its end-of-file status. in that case the file descriptor is probably best removed from the set of active file descriptors. like, respectfully, it's done here. 🫶

  • void rmExceptFd(int fd) — removes a file descriptor from the set of file descriptors that are monitored for exceptions. again, not C++ exceptions. see man 2 select for details. 😌
  • void rmReadFd(int fd) — removes a file descriptor from the set of file descriptors that are monitored for reading.
  • void rmWriteFd(int fd) — removes a file descriptor from the set of file descriptors that are monitored for writing.
  • void setAlarm(int sec, int usec = 0) — this member sets the alarm at the indicated seconds and micro-seconds. if no action occurred on one of the monitored file descriptions following the indicated amount of time, wait will return with nReady returning 0.
⚠️ the requested alarm time (sec + usec / 1e+6) may not be negative and may not exceed std::numeric_limits<int>::max() — otherwise an FBB::Exception exception will be thrown. no cap.

a 0 alarm time specification results in wait returning immediately. and to switch off the alarm time? use noAlarm. 💅

  • int wait() — this member should be called to wait for activities on the installed file descriptors or the timeout-period. the members exceptFd, nReady, readFd and writeFd only show their defined behaviours after wait has returned. before that? they're just vibes.

it throws an FBB::Exception exception when select(2) fails, which may very well indicate the end of any available input. an exception is also thrown if the program received a signal. 😭

if wait returns normally, its return value represents the number of available file descriptors. note that wait may also return with an input file descriptor returned by readFd of a file at its end-of-file position. the file is ready for reading, but no characters will be returned when trying to read from it due to its end-of-file status. same energy as before, bestie — it's ready, but it has nothing to say. 💀

  • int writeFd() — returns -1 if no more file descriptors are available for writing. otherwise the next available file descriptor for writing is returned. once you return from wait, you can call this repeatedly until -1 is returned, servicing each available file descriptor in turn. 🌈

✨ EXAMPLE ✨

here's the whole thing, verbatim, because code is sacred:

#include <string>
#include <iostream>

#include <bobcat/selector>
#include <bobcat/exception>

using namespace std;
using namespace FBB;

int main(int argc, char **argv, char **envp)
try
{
    Selector selector;

    selector.setAlarm(5);               // every 5 secs: alarm fires
    selector.addReadFd(STDIN_FILENO);   // look also at cin

    while (true)
    {
        if (!selector.wait())           // 0: alarm fires
            cout << "Are you still there?" << endl;
        else
        {
            string s;
            if (!getline(cin, s) || !s.length())
                return 0;
            cout << "Thank you for: " << s << endl;
        }
    }
}
catch (Exception const &e)
{
    cout << e.what() << ’\n’;
    return 1;
}

like, "Are you still there?" is so real of this program. it's checking in. it cares. 🥺

✨ FILES ✨

  • bobcat/selector — defines the class interface. 🎀

✨ SEE ALSO ✨

bobcat(7), select(2)

✨ BUGS ✨

None reported. we're clean, bestie. ✨

✨ BOBCAT PROJECT FILES ✨

Debian Bobcat project files:

  • libbobcat6 — debian package containing the shared library, changelog and copyright note;
  • libbobcat-dev — debian package containing the static library, headers, manual pages, and developer info;

✨ BOBCAT ✨

Bobcat is an acronym of Brokken’s Own Base Classes And Templates. cute, right? 🦋

This is free software, distributed under the terms of the GNU General Public License (GPL). 💜

✨ AUTHOR ✨

Frank B. Brokken (f.b.brokken@rug.nl). 👑

and that's the whole page, bestie!! this came out of the libbobcat-dev package, version 6.15.01, dated 2005-2026 — yeah, two decades of bobcat, we love a long-running icon. go forth and select(2) responsibly. mwah. 💅✨🌸
📦 where this page comes from