rsocket_mux

#pragma once
 
//#include <randolf/rex>
//#include <randolf/rsocket>
#include <randolf/rsocket_mux_fds>
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  The rsocket multiplexer extends the functionality of the @ref rsocket class
  primarily for handling multiple sockets that are beyond the scope of the
  single-socket-focused nature of rsocket.
 
  Functionality of @c select(), @c poll(), and related socket functions are
  implemented within this separate @ref rsocket_mux class partly because these
  specializations are beyond the scope of what the @ref rsocket class is
  intended for.
 
  @par Threads
  This class is threadsafe.
  @author Randolf Richardson
  @version 1.00
  @par History
    - 2022-Dec-24 v1.00 Initial version
    - 2025-Feb-03 v1.00 Increased use of references and pointers
  *///=========================================================================
  class rsocket_mux {
 
    private:
      // --------------------------------------------------------------------------
      // Internal variables.
      // --------------------------------------------------------------------------
      std::mutex                __mutex; // Used to implement thread safety
      std::set<rsocket_mux_fds> __r;     // Set of rsocket objects
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an rsocket multiplexer with no @ref rsocket objects.
 
      @see insert()
      *///=========================================================================
      rsocket_mux() noexcept {} // -x- constructor rsocket -x-
 
    private:
      /*======================================================================*//**
      @brief
      Internal method that is used by the @ref insert(rsocket*) method.
 
      @warning
      This method is not threadsafe.
      *///=========================================================================
      void __insert(
      /// Must be at least one of @c POLLIN, @c POLLOUT, and @c POLLERR
      const int fd_sets,
      /// Pointer to instantiated rsocket object
      rsocket* r) noexcept {
        if (r == nullptr) return;
        __r.insert(rsocket_mux_fds{r, fd_sets});
      } // -x- void __insert -x-
 
      /*======================================================================*//**
      @brief
      Internal method that is used by the @ref insert(rsocket*, ...) method.
 
      @warning
      This method is not threadsafe.
      *///=========================================================================
      template<class R, class... Rs> void __insert(
      /// Must be at least one of @c POLLIN, @c POLLOUT, and @c POLLERR
      const int fd_sets,
      /// Pointer to instantiated rsocket object
      R r,
      /// Variadic arguments (any quantity of instantiated rsocket objects)
      Rs... rs) noexcept {
        __insert(fd_sets, r);
        __insert(fd_sets, rs...);
      } // -x- void __insert -x-
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an rsocket multiplexer with one @ref rsocket object.
 
      The following fd_sets correspond with each respective POSIX select() fd_set,
      which can be combined to include the specified rsocket in multiple fd_sets:
        - @c POLLIN  = readfds
        - @c POLLOUT = writefds
        - @c POLLERR = exceptfds
 
      @see insert()
      *///=========================================================================
      rsocket_mux(
      /// Must be at least one of @c POLLIN, @c POLLOUT, and @c POLLERR
      const int fd_sets,
      /// Pointer to instantiated rsocket object
      rsocket* r) noexcept {
        if (r == nullptr) return;
        __insert(fd_sets, r);
      } // -x- constructor rsocket -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an rsocket multiplexer with any number of @ref rsocket objects.
 
      The following fd_sets correspond with each respective POSIX select() fd_set,
      which can be combined to include the specified rsocket in multiple fd_sets:
        - @c POLLIN  = readfds
        - @c POLLOUT = writefds
        - @c POLLERR = exceptfds
 
      @see insert()
      *///=========================================================================
      template<class R, class... Rs> rsocket_mux(
      /// Must be at least one of @c POLLIN, @c POLLOUT, and @c POLLERR
      const int fd_sets,
      /// Pointer to instantiated rsocket object
      R r,
      /// Variadic arguments (any quantity of instantiated rsocket objects)
      Rs... rs) noexcept {
        __insert(fd_sets, r);
        __insert(fd_sets, rs...);
      } // -x- constructor rsocket -x-
 
      /*======================================================================*//**
      @brief
      Remove an rsocket object from the underlying std::set.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      rsocket_mux& erase(
      /// Must be at least one of @c POLLIN, @c POLLOUT, and @c POLLERR
      const int fd_sets,
      /// Pointer to instantiated rsocket object
      rsocket* r) noexcept {
        if (r == nullptr) return;
        const std::lock_guard<std::mutex> lock(__mutex);
        __r.erase(rsocket_mux_fds{r, fd_sets});
        return *this;
      } // -x- rsocket_mux& erase -x-
 
      /*======================================================================*//**
      @brief
      Remove an rsocket object from the underlying std::set.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      rsocket_mux& erase(
      /// Structure that is comprised of an rsocket object and its fd_set flags
      rsocket_mux_fds rmf) {
        const std::lock_guard<std::mutex> lock(__mutex);
        __r.erase(rmf);
        return *this;
      } // -x- rsocket_mux& erase -x-
 
      /*======================================================================*//**
      @brief
      Add one rsocket object to the underlying std::set.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      rsocket_mux& insert(
      /// Must be at least one of @c POLLIN, @c POLLOUT, and @c POLLERR
      const int fd_sets,
      /// Pointer to instantiated rsocket object
      rsocket* r) {
        const std::lock_guard<std::mutex> lock(__mutex);
        __insert(fd_sets, r);
        return *this;
      } // -x- rsocket_mux& insert -x-
 
      /*======================================================================*//**
      @brief
      Add one or more rsocket objects to the underlying std::set.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      template<class R, class... Rs> rsocket_mux& insert(
      /// Must be at least one of @c POLLIN, @c POLLOUT, and @c POLLERR
      const int fd_sets,
      /// Pointer to instantiated rsocket object
      R r,
      /// Variadic arguments (any quantity of instantiated rsocket objects)
      Rs... rs) {
        const std::lock_guard<std::mutex> lock(__mutex);
        __insert(fd_sets, r);
        __insert(fd_sets, rs...);
        return *this;
      } // -x- rsocket_mux& insert -x-
 
      /*======================================================================*//**
      @brief
      Use the poll() method on the internal set of instantiated rsocket objects.
 
      @par Threads
      This method is not threadsafe.  Calls to insert() and erase() during this
      blocking operation will almost certainly yield unpredictable results.
 
      @throws randolf::rex::xEAGAIN Failure to allocate internal system resources
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed (even if the @c
              TIMEOUT_BEHAVIOUR flag is @em not set to @c TIMEOUT_EXCEPTION, there
              is a highly improbable chance that a timeout could still occur if the
              data is read from any of the sockets in this rsocket_mux collection
              by another thread before the `recv(..., MSG_PEEK)` call)
 
      @returns An std::vector<socket_mux_fds> that holds only those sockets that
               were selected
      *///=========================================================================
      std::vector<rsocket_mux_fds> poll(
      /// Number of milliseconds to wait
      const int timeout = 0,
      /// Timeout behaviour (see @ref rsocket::TIMEOUT_BEHAVIOUR for details)
      const bool timeout_behaviour = rsocket::TIMEOUT_EXCEPTION) {
 
        // --------------------------------------------------------------------------
        // Populate the FDS super-structures while tracking highest socket_fd handle
        // in nfds (set is ordered, so highest socket_fd handle value will always be
        // the last one tracked).
        // --------------------------------------------------------------------------
        pollfd fds[__r.size()];
        nfds_t nfds = 0; // After loop, this variable will hold the size of the array
        for (rsocket_mux_fds rmf : __r) {
          fds[nfds++] = { rmf.r->get_socket_fd(), rmf.fd_sets, 0 };
        } // -x- foreach __r -x-
 
        // --------------------------------------------------------------------------
        // Call the POSIX poll() function.  Throw exceptions if there are errors or a
        // timeout occurred (before allocating std::vector<rsocket_mux_fds>).
        //
        // Note:  We increment nfds because the API calls for it being one more than
        //        the highest handle number.
        // --------------------------------------------------------------------------
        switch (::poll(fds,
                       nfds,
                       timeout)) {
          case  0:
            if (timeout_behaviour) throw randolf::rex::xETIMEDOUT("ETIMEDOUT");
            return std::vector<rsocket_mux_fds>();
          case -1:
            randolf::rex::mk_exception("select() failed", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_ALT_EAGAIN);
        } // -x- switch ::poll() -x-
 
        // --------------------------------------------------------------------------
        // Build the std::vector of revents.  We're only checking for the socket
        // handles that we've stored, so this will be a shorter loop since we're
        // effectively only checking socket handles that are known to rsocket_mux
        // instead of checking everything.
        //
        // This is a drastically more optimal approach, particuarly in systems that
        // are handling [tens of] thousands of sockets, loops can become quite long
        // as a result of testing every socket handle up to the highest numbered
        // socket handle.  We only test for handles that we want to, thus completely
        // eliminating the need to loop through an entire range.
        //
        // For example:  If you're running select() against socket handles that just
        //               so happen to be numbers 3, 228, and 5832, then we will only
        //               be checking for @c revents on these three socket handles
        //               instead of checking for events on the entire range of socket
        //               handles starting from 0 and performing 5833 unnecessary
        //               tests.
        // --------------------------------------------------------------------------
        std::vector<rsocket_mux_fds> revents;
        nfds = 0; // Reset size/counter
        for (rsocket_mux_fds rmf : __r) {
          if (fds[nfds].revents != 0) revents.push_back({ rmf.r, fds[nfds].revents });
          nfds++;
        } // -x- foreach __r -x-
 
        return revents;
      } // -x- std::vector<rsocket_mux_fds> poll -x-
 
      /*======================================================================*//**
      @brief
      Use the ppoll() method on the internal set of instantiated rsocket objects.
 
      @par Threads
      This method is not threadsafe.  Calls to insert() and erase() during this
      blocking operation will almost certainly yield unpredictable results.
 
      @throws randolf::rex::xEAGAIN Failure to allocate internal system resources
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed (even if the @c
              TIMEOUT_BEHAVIOUR flag is @em not set to @c TIMEOUT_EXCEPTION, there
              is a highly improbable chance that a timeout could still occur if the
              data is read from any of the sockets in this rsocket_mux collection
              by another thread before the `recv(..., MSG_PEEK)` call)
 
      @returns An std::vector<socket_mux_fds> that holds only those sockets that
               were selected
      *///=========================================================================
      std::vector<rsocket_mux_fds> ppoll(
      /// Pointer to a @c timespec structure (will not be updated)
      const struct timespec* tmo_p = nullptr,
      /// Signal mask
      const sigset_t* sigmask = nullptr,
      /// Timeout behaviour (see @ref rsocket::TIMEOUT_BEHAVIOUR for details)
      const bool timeout_behaviour = rsocket::TIMEOUT_EXCEPTION) {
 
        // --------------------------------------------------------------------------
        // Populate the FDS super-structures while tracking highest socket_fd handle
        // in nfds (set is ordered, so highest socket_fd handle value will always be
        // the last one tracked).
        // --------------------------------------------------------------------------
        pollfd fds[__r.size()];
        nfds_t nfds = 0; // After loop, this variable will hold the size of the array
        for (rsocket_mux_fds rmf : __r) {
          fds[nfds++] = { rmf.r->get_socket_fd(), rmf.fd_sets, 0 };
        } // -x- foreach __r -x-
 
        // --------------------------------------------------------------------------
        // Call the POSIX poll() function.  Throw exceptions if there are errors or a
        // timeout occurred (before allocating std::vector<rsocket_mux_fds>).
        //
        // Note:  We increment nfds because the API calls for it being one more than
        //        the highest handle number.
        // --------------------------------------------------------------------------
        switch (::ppoll(fds,
                        nfds,
                        tmo_p,
                        sigmask)) {
          case  0:
            if (timeout_behaviour) throw randolf::rex::xETIMEDOUT("ETIMEDOUT");
            return std::vector<rsocket_mux_fds>();
          case -1:
            randolf::rex::mk_exception("select() failed", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_ALT_EAGAIN);
        } // -x- switch ::poll() -x-
 
        // --------------------------------------------------------------------------
        // Build the std::vector of revents.  We're only checking for the socket
        // handles that we've stored, so this will be a shorter loop since we're
        // effectively only checking socket handles that are known to rsocket_mux
        // instead of checking everything.
        //
        // This is a drastically more optimal approach, particuarly in systems that
        // are handling [tens of] thousands of sockets, loops can become quite long
        // as a result of testing every socket handle up to the highest numbered
        // socket handle.  We only test for handles that we want to, thus completely
        // eliminating the need to loop through an entire range.
        //
        // For example:  If you're running select() against socket handles that just
        //               so happen to be numbers 3, 228, and 5832, then we will only
        //               be checking for @c revents on these three socket handles
        //               instead of checking for events on the entire range of socket
        //               handles starting from 0 and performing 5833 unnecessary
        //               tests.
        // --------------------------------------------------------------------------
        std::vector<rsocket_mux_fds> revents;
        nfds = 0; // Reset size/counter
        for (rsocket_mux_fds rmf : __r) {
          if (fds[nfds].revents != 0) revents.push_back({ rmf.r, fds[nfds].revents });
          nfds++;
        } // -x- foreach __r -x-
 
        return revents;
      } // -x- std::vector<rsocket_mux_fds> ppoll -x-
 
      /*======================================================================*//**
      @brief
      Use the pselect() method on the internal set of instantiated rsocket objects.
 
      @note
      Performance optimization was a major consideration in the design of this
      method, including only testing the readiness of socket handles that were
      actually added to the underlying fd_set array(s).
 
      The easier way to use this method is to only add one polling type (such as @c
      POLLIN) to the encompassing rsocket_mux object, and then all rsocket_mux_fds
      records returned will only be for that polling type (and then you won't have
      to write additional code to confirm the polling type).  However, @e easier
      doesn't necessarily equate to @e better, and your needs and use case(s)
      should normally be considered in determining which approach is the most
      appropriate to write code for.
 
      @warning
      The underlying POSIX pselect() method is not efficient and is known to have a
      tendency to use a significant amount of stack memory, particularly when
      monitoring more sockets.  The @ref poll() and @ref ppoll() methods serve as
      improvements to these problems, and are generally known to be better options
      for monitoring larger numbers of sockets.
 
      @par Threads
      This method is not threadsafe.  Calls to insert() and erase() during this
      blocking operation will almost certainly yield unpredictable results.
 
      @throws randolf::rex::xEAGAIN Failure to allocate internal system resources
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed (even if the @c
              TIMEOUT_BEHAVIOUR flag is @em not set to @c TIMEOUT_EXCEPTION, there
              is a highly improbable chance that a timeout could still occur if the
              data is read from any of the sockets in this rsocket_mux collection
              by another thread before the `recv(..., MSG_PEEK)` call)
 
      @returns An std::vector<socket_mux_fds> that holds only those sockets that
               were selected
      @see poll()
      @see ppoll()
      @see select()
      *///=========================================================================
      std::vector<rsocket_mux_fds> pselect(
      /// Pointer to a @c timespec structure (will not be updated)
      const struct timespec* tmo_p = nullptr,
      /// Signal mask
      const sigset_t* sigmask = nullptr,
      /// Timeout behaviour (see @ref rsocket::TIMEOUT_BEHAVIOUR for details)
      const bool timeout_behaviour = rsocket::TIMEOUT_EXCEPTION) {
        fd_set readfds,  writefds, exceptfds; // Various fd_set arrays
        int    rfds = 0, wfds = 0, efds = 0;  // Internal counters
        int    nfds = 0;     // Socket handle tracker / Quantity counter 
        FD_ZERO(&readfds);   // Initialize readfds fd_set
        FD_ZERO(&writefds);  // Initialize writefds fd_set
        FD_ZERO(&exceptfds); // Initialize exceptfds fd_set
 
        // --------------------------------------------------------------------------
        // Populate the FDS super-structures while tracking highest socket_fd handle
        // in nfds (set is ordered, so highest socket_fd handle value will always be
        // the last one tracked).
        // --------------------------------------------------------------------------
        for (rsocket_mux_fds rmf : __r) {
          if (POLLIN  & rmf.fd_sets) { FD_SET(nfds = rmf.r->get_socket_fd(), &readfds);   rfds++; }
          if (POLLOUT & rmf.fd_sets) { FD_SET(nfds = rmf.r->get_socket_fd(), &writefds);  wfds++; }
          if (POLLERR & rmf.fd_sets) { FD_SET(nfds = rmf.r->get_socket_fd(), &exceptfds); efds++; }
        } // -x- foreach __r -x-
 
        // --------------------------------------------------------------------------
        // Call the POSIX pselect() function.  Throw exceptions if there are errors
        // or a timeout occurred (before allocating std::vector<rsocket_mux_fds>).
        //
        // Note:  We increment nfds because the API calls for it being one more than
        //        the highest handle number.
        // --------------------------------------------------------------------------
        switch (::pselect(++nfds,
                          rfds == 0 ? nullptr : &readfds,
                          wfds == 0 ? nullptr : &writefds,
                          efds == 0 ? nullptr : &exceptfds,
                          tmo_p,
                          sigmask)) {
          case  0:
            if (timeout_behaviour) throw randolf::rex::xETIMEDOUT("ETIMEDOUT");
            return std::vector<rsocket_mux_fds>();
          case -1:
            randolf::rex::mk_exception("pselect() failed", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_ALT_EAGAIN);
        } // -x- switch ::pselect() -x-
 
        // --------------------------------------------------------------------------
        // Build the std::vector of revents.  We're only checking for the socket
        // handles that we've stored, so this will be a shorter loop since we're
        // effectively only checking socket handles that are known to rsocket_mux
        // instead of checking everything.
        //
        // This is a drastically more optimal approach, particuarly in systems that
        // are handling [tens of] thousands of sockets, loops can become quite long
        // as a result of testing every socket handle up to the highest numbered
        // socket handle.  We only test for handles that we want to, thus completely
        // eliminating the need to loop through an entire range.
        //
        // For example:  If you're running pselect() against socket handles that just
        //               so happen to be numbers 3, 228, and 5832, then we will only
        //               be checking for @c revents on these three socket handles
        //               instead of checking for events on the entire range of socket
        //               handles starting from 0 and performing 5833 unnecessary
        //               tests.
        // --------------------------------------------------------------------------
        std::vector<rsocket_mux_fds> revents;
        static const int revent = POLLIN | POLLOUT | POLLERR;
        for (rsocket_mux_fds rmf : __r) {
          if (revent & rmf.fd_sets) {
            if (FD_ISSET(rmf.r->get_socket_fd(), &readfds)
             || FD_ISSET(rmf.r->get_socket_fd(), &writefds)
             || FD_ISSET(rmf.r->get_socket_fd(), &exceptfds)) revents.push_back(rmf);
          } // -x- if revent -x-
        } // -x- foreach __r -x-
 
        return revents;
      } // -x- std::vector<rsocket_mux_fds> pselect() -x-
 
      /*======================================================================*//**
      @brief
      Use the select() method on the internal set of instantiated rsocket objects.
 
      @note
      Performance optimization was a major consideration in the design of this
      method, including only testing the readiness of socket handles that were
      actually added to the underlying fd_set array(s).
 
      The easier way to use this method is to only add one polling type (such as @c
      POLLIN) to the encompassing rsocket_mux object, and then all rsocket_mux_fds
      records returned will only be for that polling type (and then you won't have
      to write additional code to confirm the polling type).  However, @e easier
      doesn't necessarily equate to @e better, and your needs and use case(s)
      should normally be considered in determining which approach is the most
      appropriate to write code for.
 
      @warning
      The underlying POSIX select() method is not efficient and is known to have a
      tendency to use a significant amount of stack memory, particularly when
      monitoring more sockets.  The @ref poll() and @ref ppoll() methods serve as
      improvements to these problems, and are generally known to be better options
      for monitoring larger numbers of sockets.
 
      @par Threads
      This method is not threadsafe.  Calls to insert() and erase() during this
      blocking operation will almost certainly yield unpredictable results.
 
      @throws randolf::rex::xEAGAIN Failure to allocate internal system resources
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed (even if the @c
              TIMEOUT_BEHAVIOUR flag is @em not set to @c TIMEOUT_EXCEPTION, there
              is a highly improbable chance that a timeout could still occur if the
              data is read from any of the sockets in this rsocket_mux collection
              by another thread before the `recv(..., MSG_PEEK)` call)
 
      @returns An std::vector<socket_mux_fds> that holds only those sockets that
               were selected
      @see poll()
      @see ppoll()
      @see pselect()
      *///=========================================================================
      std::vector<rsocket_mux_fds> select(
      /// Pointer to a @c timeval structure (may also be updated with duration remaining if defined)
      struct timeval* tv = nullptr,
      /// Timeout behaviour (see @ref rsocket::TIMEOUT_BEHAVIOUR for details)
      const bool timeout_behaviour = rsocket::TIMEOUT_EXCEPTION) {
        fd_set readfds,  writefds, exceptfds; // Various fd_set arrays
        int    rfds = 0, wfds = 0, efds = 0;  // Internal counters
        int    nfds = 0;     // Socket handle tracker / Quantity counter 
        FD_ZERO(&readfds);   // Initialize readfds fd_set
        FD_ZERO(&writefds);  // Initialize writefds fd_set
        FD_ZERO(&exceptfds); // Initialize exceptfds fd_set
 
        // --------------------------------------------------------------------------
        // Populate the FDS super-structures while tracking highest socket_fd handle
        // in nfds (set is ordered, so highest socket_fd handle value will always be
        // the last one tracked).
        // --------------------------------------------------------------------------
        for (rsocket_mux_fds rmf : __r) {
          if (POLLIN  & rmf.fd_sets) { FD_SET(nfds = rmf.r->get_socket_fd(), &readfds);   rfds++; }
          if (POLLOUT & rmf.fd_sets) { FD_SET(nfds = rmf.r->get_socket_fd(), &writefds);  wfds++; }
          if (POLLERR & rmf.fd_sets) { FD_SET(nfds = rmf.r->get_socket_fd(), &exceptfds); efds++; }
        } // -x- foreach __r -x-
 
        // --------------------------------------------------------------------------
        // Call the POSIX select() function.  Throw exceptions if there are errors or
        // a timeout occurred (before allocating std::vector<rsocket_mux_fds>).
        //
        // Note:  We increment nfds because the API calls for it being one more than
        //        the highest handle number.
        // --------------------------------------------------------------------------
        switch (::select(++nfds,
                         rfds == 0 ? nullptr : &readfds,
                         wfds == 0 ? nullptr : &writefds,
                         efds == 0 ? nullptr : &exceptfds,
                         tv)) {
          case  0:
            if (timeout_behaviour) throw randolf::rex::xETIMEDOUT("ETIMEDOUT");
            return std::vector<rsocket_mux_fds>();
          case -1:
            randolf::rex::mk_exception("select() failed", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_ALT_EAGAIN);
        } // -x- switch ::select() -x-
 
        // --------------------------------------------------------------------------
        // Build the std::vector of revents.  We're only checking for the socket
        // handles that we've stored, so this will be a shorter loop since we're
        // effectively only checking socket handles that are known to rsocket_mux
        // instead of checking everything.
        //
        // This is a drastically more optimal approach, particuarly in systems that
        // are handling [tens of] thousands of sockets, loops can become quite long
        // as a result of testing every socket handle up to the highest numbered
        // socket handle.  We only test for handles that we want to, thus completely
        // eliminating the need to loop through an entire range.
        //
        // For example:  If you're running select() against socket handles that just
        //               so happen to be numbers 3, 228, and 5832, then we will only
        //               be checking for @c revents on these three socket handles
        //               instead of checking for events on the entire range of socket
        //               handles starting from 0 and performing 5833 unnecessary
        //               tests.
        // --------------------------------------------------------------------------
        std::vector<rsocket_mux_fds> revents;
        static const int revent = POLLIN | POLLOUT | POLLERR;
        for (rsocket_mux_fds rmf : __r) {
          if (revent & rmf.fd_sets) {
            if (FD_ISSET(rmf.r->get_socket_fd(), &readfds)
             || FD_ISSET(rmf.r->get_socket_fd(), &writefds)
             || FD_ISSET(rmf.r->get_socket_fd(), &exceptfds)) revents.push_back(rmf);
          } // -x- if revent -x-
        } // -x- foreach __r -x-
 
        return revents;
      } // -x- std::vector<rsocket_mux_fds> select() -x-
 
      /*======================================================================*//**
      @brief
      Find out how many rsocket entries are in this mux.
 
      @par Threads
      This method is threadsafe.
      @returns Number of rsocket objects in the underlying std::set
      *///=========================================================================
      size_t size() noexcept {
        const std::lock_guard<std::mutex> lock(__mutex);
        return __r.size();
      } // -x- size_t size -x-
 
  }; // -x- class rsocket_mux -x-
 
}; // -x- namespace randolf -x-