rsocket_group

#pragma once
 
//#include <randolf/rex>
//#include <randolf/rsocket>
#include <randolf/rsocket_group_rc>
#include <randolf/rtools>
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  An rsocket_group provides a means to associate multiple @ref rsocket objects
  so that the same operation can be performed on all of them at once.
 
  The @ref rsocket::accept() and @ref rsocket::accept4() methods can also be
  configured to automatically assign group membership to new connections, which
  can be particularly useful for certain types of multi-user systems.
 
  @par Threads
  This class is threadsafe.
  @author Randolf Richardson
  @version 1.00
  @par History
  2022-Dec-29 v1.00 Initial version
  *///=========================================================================
  class rsocket_group {
 
    private:
      // --------------------------------------------------------------------------
      // Comparator for use with std::set<rsocket> initialization.  It simply
      // compares the physical address of the instantiated rsocket() object since
      // this is immediately available for the fastest possible comparison.
      // --------------------------------------------------------------------------
      template<typename R> struct __rsocket_cmp {
        bool operator() (const std::weak_ptr<rsocket> r1, const std::weak_ptr<rsocket> r2) const {
          auto _r1 = r1.lock(); if (!_r1) return false; // Expired pointer; we're done
          auto _r2 = r2.lock(); if (!_r1) return true;  // Not expired-after-expired pointer
          return (uintptr_t)_r1.get() < (uintptr_t)_r2.get(); // Compare pointers as uint values
        } // -x- bool operator() -x-
      }; // -x- struct __rsocket_cmp -x-
 
      // --------------------------------------------------------------------------
      // Internal variables.
      // --------------------------------------------------------------------------
      std::mutex                                               __mutex; // Used to ensure thread safety
      std::set<std::weak_ptr<rsocket>, __rsocket_cmp<rsocket>> __r;     // Set of rsocket objects (with our comparator)
 
      // --------------------------------------------------------------------------
      // Keep track of test for whether this host stores integers using big endian.
      // --------------------------------------------------------------------------
      inline static const bool                                 __endian_is_msb = htons(42) == 42; // TRUE==MSB / FALSE==LSB
 
      // --------------------------------------------------------------------------
      // General variables.  Atomic variables are used for variables as needed to
      // support operations in a thread-safe manner.
      // --------------------------------------------------------------------------
      std::string                                              __name;
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an rsocket group with no @ref rsocket objects.
 
      @see insert()
      *///=========================================================================
      rsocket_group() noexcept {}; // -x- constructor rsocket_group -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an rsocket group with any number of @ref rsocket objects.
 
      @see insert()
      *///=========================================================================
      template<class R, class... Rs> rsocket_group(
      /// Pointer to instantiated rsocket object
      R r,
      /// Variadic arguments (any quantity of instantiated rsocket objects)
      Rs... rs) noexcept {
        __insert(r);
        __insert(rs...);
      }; // -x- constructor rsocket_group -x-
 
    private:
      /*======================================================================*//**
      @brief
      Internal method that is used by the @ref insert(rsocket*) method.
 
      @warning
      This method is not threadsafe.
      *///=========================================================================
      void __insert(
      /// Pointer to instantiated rsocket object
      rsocket* r) noexcept {
        if (r == nullptr) return;
        __r.insert(std::make_shared<rsocket>(r)); // Effectively: std::make_weak()
      }; // -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(
      /// Pointer to instantiated rsocket object
      R r,
      /// Variadic arguments (any quantity of instantiated rsocket objects)
      Rs... rs) noexcept {
        __insert(r);
        __insert(rs...);
      }; // -x- void __insert -x-
 
    public:
      /*======================================================================*//**
      @brief
      Close all rsocketss that are in this rsocket_group.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::close()
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> close() {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::vector<rsocket_group_rc> v1;
        std::vector<rsocket_group_rc> v2;
 
        // --------------------------------------------------------------------------
        // Loop through all rsocket objects in the underlying std::set.
        //
        // We don't need a mutex lock here because the close() method is threadsafe.
        // --------------------------------------------------------------------------
        for (std::weak_ptr<rsocket> wp : __r) {
          if (auto r = wp.lock()) { // Weak pointer is still valid, so acquire a std::shared_ptr while we access r
            try {
              r->close();
              v1.push_back({r.get(), 0, nullptr});
            } catch (std::exception* e) {
              v2.push_back({r.get(), 0, e});
            }
          } // -x- if r.lock() -x-
        } // -x- foreach __r -x-
 
        return std::pair(v1, v2);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> shutdown -x-
 
      /*======================================================================*//**
      @brief
      Remove an rsocket object from the underlying std::set.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      void erase(
      /// Pointer to instantiated rsocket object
      rsocket* r) {
        const std::lock_guard<std::mutex> lock(__mutex);
        __r.erase(std::make_shared<rsocket>(r)); // Effectively: std::make_weak()
      }; // -x- void erase -x-
 
      /*======================================================================*//**
      @brief
      Add one rsocket object to the underlying std::set.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      void insert(
      /// Pointer to instantiated rsocket object
      rsocket* r) {
        const std::lock_guard<std::mutex> lock(__mutex);
        __insert(r);
      }; // -x- void 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> void insert(
      /// 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(r);
        __insert(rs...);
      }; // -x- void insert -x-
 
      /*======================================================================*//**
      @brief
      Specify a name for this rsocket_group.
 
      This is an arbitrary name that is entirely optional, and should be regarded
      as similar to the naming of threads.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      void name(
      /// Name to assign to this rsocket_group
      const std::string name) noexcept {
        const std::lock_guard<std::mutex> lock(__mutex);
        __name = name;
      }; // -x- void name -x-
 
      /*======================================================================*//**
      @brief
      Find out what this rsocket_group's name is.
 
      @par Threads
      This method is threadsafe.
      @returns The name of this rsocket (or an empty std::string if this rsocket
               doesn't have a name)
      *///=========================================================================
      std::string name() noexcept {
        const std::lock_guard<std::mutex> lock(__mutex);
        return __name;
      }; // -x- std::string name -x-
 
      /*======================================================================*//**
      @brief
      Get the combined total of socket I/O statistics from all rsocket objects in
      this group.
 
      The number of bytes transmitted and received is tracked internally, so that
      the information can be used later in logging.  These statistics are available
      at all times, but for logging purposes it makes the most sense to copy this
      information after the rsocket is closed, at which time the final statistics
      will continue to be available until the rsocket's destructor takes over.
 
      @par Threads
      This method is threadsafe.
      @returns rsocket_io wrapped in a std::shared_ptr object to help ease memory
               management efforts
      @see rsocket::net_io()
      *///=========================================================================
      std::shared_ptr<rsocket_io> net_io() noexcept {
        std::shared_ptr stats = std::make_shared<rsocket_io>();
 
        // --------------------------------------------------------------------------
        // Loop through all rsocket objects in the underlying std::set.
        //
        // We don't need a mutex lock here because the stastical rx/tx counters in
        // every rsocket class are atomic variables.
        // --------------------------------------------------------------------------
        for (std::weak_ptr<rsocket> wp : __r) {
          if (auto r = wp.lock()) { // Weak pointer is still valid, so acquire a std::shared_ptr while we access r
            stats->bytes_rx += r->__bytes_rx;
            stats->bytes_tx += r->__bytes_tx;
            stats->crypt_rx += r->__crypt_rx;
            stats->crypt_tx += r->__crypt_tx;
          } // -x- if r.lock() -x-
        } // -x- foreach __r -x-
 
        return stats;
      }; // -x- std::shared_ptr<rsocket_io> net_io -x-
 
      /*======================================================================*//**
      @brief
      Get combined total of socket I/O statistics from all rsocket objects in this
      group as a pre-formatted std::string object.
 
      See the @ref rsocket::net_io method for full documentation.
 
      @par Threads
      This method is threadsafe.
      @returns An interpolated format string as an std::string object.
      @see rsocket::net_io(const char*, size_t len)
      *///=========================================================================
      std::string net_io(
      /// Format string
      const char* format,
      /// Length of format string (in bytes), or 0 to auto-detect length if format string is an ASCIIZ string
      size_t len = 0) noexcept {
        return rsocket().net_io(format, len, net_io().get()); // Call rsocket's net_io method on our internally-gathered group rsocket_io statistics
      }; // -x- std::string net_io -x-
 
    private:
      /*======================================================================*//**
      @brief
      Send data to all rsocket endpoints that are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::__send(void*, size_t, int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> __send(
      /// Data to send
      const void* msg,
      /// Number of bytes to send
      const size_t len,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::vector<rsocket_group_rc> v1;
        std::vector<rsocket_group_rc> v2;
 
        // --------------------------------------------------------------------------
        // Loop through all rsocket objects in the underlying std::set.
        //
        // We don't need a mutex lock here because the __send method is threadsafe.
        // --------------------------------------------------------------------------
        for (std::weak_ptr<rsocket> wp : __r) {
          if (auto r = wp.lock()) { // Weak pointer is still valid, so acquire a std::shared_ptr while we access r
            if (r->__debug) r->debug("rsocket_group::send(socket{0x" + randolf::rtools::to_hex(r->__socket_fd) + "}"
                                   + ", <std::string>"
                                   + ", " + std::to_string(len)
                                   + ", " + std::to_string(flags)
                                   + ");");
            try {
              v1.push_back({r.get(), r->__send(msg, len, flags), nullptr});
            } catch (std::exception* e) {
              v2.push_back({r.get(), 0, e});
            }
          } // -x- if r.lock() -x-
        } // -x- foreach __r -x-
 
        return std::pair(v1, v2);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> __send -x-
 
      /*======================================================================*//**
      @brief
      Send data that included a final EoL sequence to all rsocket endpoints that
      are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::__sendline(void*, size_t, int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> __sendline(
      /// Data to send
      const void*  msg,
      /// Number of bytes to send
      const size_t len,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int    flags = 0) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::vector<rsocket_group_rc> v1;
        std::vector<rsocket_group_rc> v2;
 
        // --------------------------------------------------------------------------
        // Loop through all rsocket objects in the underlying std::set.
        //
        // We don't need a mutex lock here because the __sendline method is
        // threadsafe.
        // --------------------------------------------------------------------------
        for (std::weak_ptr<rsocket> wp : __r) {
          if (auto r = wp.lock()) { // Weak pointer is still valid, so acquire a std::shared_ptr while we access r
            if (r->__debug) r->debug("rsocket_group::send(socket{0x" + randolf::rtools::to_hex(r->__socket_fd) + "}"
                                   + ", <std::string>"
                                   + ", " + std::to_string(len)
                                   + ", " + std::to_string(flags)
                                   + ");");
            try {
              v1.push_back({r.get(), r->__sendline(msg, len, flags), nullptr});
            } catch (std::exception* e) {
              v2.push_back({r.get(), 0, e});
            }
          } // -x- if r.lock() -x-
        } // -x- foreach __r -x-
 
        return std::pair(v1, v2);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> __sendline -x-
 
      /*======================================================================*//**
      @brief
      Send data that is the final EoL sequence to all rsocket endpoints that are in
      this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::__sendline(void*, size_t, int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> __send_eol(
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int    flags = 0) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::vector<rsocket_group_rc> v1;
        std::vector<rsocket_group_rc> v2;
 
        // --------------------------------------------------------------------------
        // Loop through all rsocket objects in the underlying std::set.
        //
        // We don't need a mutex lock here because the __sendline method is
        // threadsafe.
        // --------------------------------------------------------------------------
        for (std::weak_ptr<rsocket> wp : __r) {
          if (auto r = wp.lock()) { // Weak pointer is still valid, so acquire a std::shared_ptr while we access r
            if (r->__debug) r->debug("rsocket_group::send_eol(socket{0x" + randolf::rtools::to_hex(r->__socket_fd) + "}"
                                   + ", " + std::to_string(flags)
                                   + ");");
            try {
              v1.push_back({r.get(), r->__send_eol(flags), nullptr});
            } catch (std::exception* e) {
              v2.push_back({r.get(), 0, e});
            }
          } // -x- if r.lock() -x-
        } // -x- foreach __r -x-
 
        return std::pair(v1, v2);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> __send_eol -x-
 
    public:
      /*======================================================================*//**
      @brief
      Send data in the form of a std::string to all rsocket endpoints that are in
      this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send(const std::string, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send(
      /// Data to send
      const std::string msg,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        return __send(msg.c_str(), msg.length(), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a std::vector<char> to all rsocket endpoints that
      are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send(const std::vector<char>, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send(
      /// Data to send
      const std::vector<char> msg,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        return __send(msg.data(), msg.size(), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a C-string to all rsocket endpoints that are in this
      rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send(const char*, const size_t, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send(
      /// Pointer to data to send
      const char* msg,
      /// Number of bytes to send
      const size_t len,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        return __send(msg, len, flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of an ASCIIZ string to all rsocket endpoints that are
      in this rsocket_group., including the terminating NULL character.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see sendz(const char*, const int) which doesn't transmit the terminating
           NULL character
      @see rsocket::send_asciiz(const char*, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_asciiz(
      /// Pointer to data to send
      const char* msg,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        return __send(msg, std::strlen(msg) + 1, flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_asciiz -x-
 
      /*======================================================================*//**
      @brief
      Send one byte of data to all rsocket endpoints that are in this
      rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send_byte(const char, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_byte(
      /// Data to send
      const char value,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        return __send(&value, sizeof(value), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_byte -x-
 
      /*======================================================================*//**
      @brief
      Send the EoL sequence to all rsocket endpoints that are in this
      rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns The same rsocket object so as to facilitate stacking
      *///=========================================================================
      template <typename T> std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_eol(
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        return __send_eol(flags);
      }; // -x- template <typename T> std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_eol -x-
 
      /*======================================================================*//**
      @brief
      Send one byte of data to all rsocket endpoints that are in this
      rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send_struct(const T, const int)
      *///=========================================================================
      template <typename T> std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_struct(
      /// Data to send
      const T value,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        return __send(&value, sizeof(value), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_struct -x-
 
      /*======================================================================*//**
      @brief
      Send one 16-bit unsigned integer of data in LSB (little endian) order to all
      rsocket endpoints that are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send_uint16_lsb(const uint16_t, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint16_lsb(
      /// Data to send
      const uint16_t value,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        uint16_t buf = !__endian_is_msb ? value : ntohs(value);
        return __send(&buf, sizeof(buf), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint16_lsb -x-
 
      /*======================================================================*//**
      @brief
      Send one 16-bit integer of data in MSB (big endian) order to all rsocket
      endpoints that are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send_uint16_msb(const uint16_t, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint16_msb(
      /// Data to send
      const uint16_t value,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        int16_t buf = __endian_is_msb ? value : htons(value);
        return __send(&buf, sizeof(buf), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_int16_msb -x-
 
      /*======================================================================*//**
      @brief
      Send one 32-bit unsigned integer of data in LSB (little endian) order to all
      rsocket endpoints that are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send_uint32_lsb(const uint32_t, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint32_lsb(
      /// Data to send
      const uint32_t value,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        uint32_t buf = !__endian_is_msb ? value : ntohl(value);
        return __send(&buf, sizeof(buf), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint32_lsb -x-
 
      /*======================================================================*//**
      @brief
      Send one 32-bit unsigned integer of data in MSB (big endian) order to all
      rsocket endpoints that are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send_uint32_msb(const uint32_t, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint32_msb(
      /// Data to send
      const uint32_t value,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        uint32_t buf = __endian_is_msb ? value : htonl(value);
        return __send(&buf, sizeof(buf), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint32_msb -x-
 
      /*======================================================================*//**
      @brief
      Send one 64-bit unsigned integer of data in LSB (little endian) order to all
      rsocket endpoints that are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send_uint64_lsb(const uint64_t, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint64_lsb(
      /// Data to send
      const uint64_t value,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        uint64_t buf = !__endian_is_msb ? value : ((((uint64_t)ntohl((value) & 0xffffffffUL)) << 32) | ntohl((uint32_t)((value) >> 32)));
        return __send(&buf, sizeof(buf), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint64_lsb -x-
 
      /*======================================================================*//**
      @brief
      Send one 64-bit unsigned integer of data in MSB (big endian) order to all
      rsocket endpoints that are in this rsocket_group.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::send_uint64_msb(const uint64_t, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint64_msb(
      /// Data to send
      const uint64_t value,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int flags = 0) {
        uint64_t buf = __endian_is_msb ? value : ((((uint64_t)htonl((value) & 0xffffffffUL)) << 32) | htonl((uint32_t)((value) >> 32)));
        return __send(&buf, sizeof(buf), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> send_uint64_msb -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a std::string to all rsocket endpoints that are in
      this rsocket_group, with an EoL sequence appended.
      @returns The same rsocket object so as to facilitate stacking
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see recvline(const size_t, const int)
      @see rsocket::sendline(const std::string, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> sendline(
      /// Data to send
      const std::string msg   = std::string(),
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int         flags = 0) {
        return __sendline(msg.c_str(), msg.length(), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> sendline -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of an ASCIIZ string to all rsocket endpoints that are
      in this rsocket_group..  The terminating NULL character won't be transmitted.
      @par Threads
      This method is threadsafe.
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see send_asciiz which also transmits the terminating NULL character
      @see rsocket::sendz(const char*, const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> sendz(
      /// Pointer to data to send
      const char* msg,
      /// MSG_DONTROUTE@n MSG_DONTWAIT@n MSG_EOR@n MSG_NOSIGNAL@n MSG_OOB
      const int   flags = 0) {
        return __send(msg, std::strlen(msg), flags);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> sendz -x-
 
      /*======================================================================*//**
      @brief
      Shut down the underlying sockets in all rsocket objects that are in this
      rsocket_group, partially or fully.
      
         SHUT_RD:    Further receives will be disallowed
         SHUT_WR:    Further sends will be disallowed (this may cause actions
                     specific to the protocol family of the socket to occur)
         SHUT_RDWR:  Further sends and receives will be disallowed (default)
      @returns A std::pair of std::vector<rsocket_group_rc> vectors, the first one
               containing successful operations that also record the number of
               bytes that were transmitted, and the second one containing failed
               operations that also record the exception that was thrown (see the
               @ref rsocket_group_rc structure for details)
      @see rsocket::shutdown(const int)
      *///=========================================================================
      std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> shutdown(
      /// SHUT_RD@n SHUT_RW@n SHUT_RDWR
      const int how = SHUT_RDWR) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::vector<rsocket_group_rc> v1;
        std::vector<rsocket_group_rc> v2;
 
        // --------------------------------------------------------------------------
        // Loop through all rsocket objects in the underlying std::set.
        //
        // We don't need a mutex lock here because the shutdown method is threadsafe.
        // --------------------------------------------------------------------------
        for (std::weak_ptr<rsocket> wp : __r) {
          if (auto r = wp.lock()) { // Weak pointer is still valid, so acquire a std::shared_ptr while we access r
            try {
              r->shutdown(how);
              v1.push_back({r.get(), 0, nullptr});
            } catch (std::exception* e) {
              v2.push_back({r.get(), 0, e});
            }
          } // -x- if r.lock() -x-
        } // -x- foreach __r -x-
 
        return std::pair(v1, v2);
      }; // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>> shutdown -x-
 
      /*======================================================================*//**
      @brief
      Find out how many rsocket entries are in this group.
 
      @par Threads
      This method is threadsafe.
      @returns Number of rsocket objects in the underlying std::set
      *///=========================================================================
      size_t size() {
        const std::lock_guard<std::mutex> lock(__mutex);
        return __r.size();
      }; // -x- size_t size -x-
 
  }; // -x- class rsocket_group -x-
 
}; // -x- namespace randolf -x-