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
    - 2025-Feb-03 v1.00 Increased use of references and pointers
    - 2025-Feb-09 v1.00 In keeping with changes in rsocket, changed most
                        methods that return data wrapped in @c std::shared_ptr
                        to return data wrapped in @c std::unique_ptr instead
                        because this has a lot less overhead, and converting
                        from unique_ptr to shared_ptr is trivial, but the other
                        way around is not directly supported
    - 2025-Feb-17 v1.00 Updated @ref net_io and related methods to include
                        support for the @c bytes_sx and @c crypt_sx statistics
  *///=========================================================================
  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.
      *///=========================================================================
      rsocket_group& __insert(
      /// Pointer to instantiated rsocket object
      rsocket* r) noexcept {
        if (r == nullptr) return *this;
        __r.insert(std::make_shared<rsocket>(r)); // Effectively: std::make_weak()
        return *this;
      } // -x- rsocket_group& __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 rsockets 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 = new std::vector<rsocket_group_rc>();
        std::vector<rsocket_group_rc>* v2 = new std::vector<rsocket_group_rc>();
        std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>>* pair = new std::pair(*v1, *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::unique_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 *pair;
      } // -x- std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>>& close -x-
 
      /*======================================================================*//**
      @brief
      Remove an rsocket object from the underlying std::set.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      rsocket_group& 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()
        }
        return *this;
      } // -x- rsocket_group& erase -x-
 
      /*======================================================================*//**
      @brief
      Add one rsocket object to the underlying std::set.
 
      @par Threads
      This method is threadsafe.
      *///=========================================================================
      rsocket_group& insert(
      /// Pointer to instantiated rsocket object
      rsocket* r) {
        const std::lock_guard<std::mutex> lock(__mutex);
        __insert(r);
        return *this;
      } // -x- rsocket_group& 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_group& 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...);
        return *this;
      } // -x- rsocket_group& 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.
      *///=========================================================================
      rsocket_group& name(
      /// Name to assign to this rsocket_group
      const std::string& name) noexcept {
        const std::lock_guard<std::mutex> lock(__mutex);
        __name = name;
        return *this;
      } // -x- rsocket_group& 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::unique_ptr object to help ease memory
               management efforts
      @see rsocket::net_io()
      *///=========================================================================
      std::unique_ptr<rsocket_io> net_io() noexcept {
        std::unique_ptr stats = std::make_unique<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::unique_ptr while we access r
            stats->bytes_rx += r->__bytes_rx;
            stats->bytes_tx += r->__bytes_tx;
            stats->bytes_sx += r->__tls ? 0 : (r->__buffer != nullptr ? r->__buffer->get_utilized() : 0); // <bytes in buffer; are these lost bytes that should be subtracted from __bytes_rx?>
            stats->crypt_rx += r->__crypt_rx;
            stats->crypt_tx += r->__crypt_tx;
            stats->crypt_sx += r->__tls ? (r->__buffer != nullptr ? r->__buffer->get_utilized() : 0) : 0; // <bytes in buffer; are these lost bytes that should be subtracted from __crypt_rx?>
          } // -x- if r.lock() -x-
        } // -x- foreach __r -x-
 
        return stats;
      } // -x- std::unique_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 = new std::vector<rsocket_group_rc>();
        std::vector<rsocket_group_rc>* v2 = new std::vector<rsocket_group_rc>();
        std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>>* pair = new std::pair(*v1, *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::unique_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 *pair;
      } // -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 = new std::vector<rsocket_group_rc>();
        std::vector<rsocket_group_rc>* v2 = new std::vector<rsocket_group_rc>();
        std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>>* pair = new std::pair(*v1, *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::unique_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 *pair;
      } // -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 = new std::vector<rsocket_group_rc>();
        std::vector<rsocket_group_rc>* v2 = new std::vector<rsocket_group_rc>();
        std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>>* pair = new std::pair(*v1, *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::unique_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 *pair;
      } // -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 = new std::vector<rsocket_group_rc>();
        std::vector<rsocket_group_rc>* v2 = new std::vector<rsocket_group_rc>();
        std::pair<std::vector<rsocket_group_rc>, std::vector<rsocket_group_rc>>* pair = new std::pair(*v1, *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::unique_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 *pair;
      } // -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() noexcept {
        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-