rsocket_io

#pragma once
 
#include <mutex>              // std::mutex
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  Structure of socket I/O statistics tracked by rsocket.
  The reason this is a subclass of @c std::mutex is to ensure a thread-safe
  operation for the @c rsocket::~rsocket destructor when making a final copy of
  the internally-tracked I/O statistics using the pointer to this structure (if
  specified with the @ref rsocket::net_io_final() method).
 
  @note
  To find out the total overall bytes received/transmitted, the sum of @ref
  bytes_rx and @ref crypt_rx , and the sum of @ref bytes_tx and @ref crypt_tx
  will provide this statistical information:
  @code{.cpp}
    #include <randolf/rsocket>
 
    std::shared_ptr<randolf::rsocket_io> io = r.net_io();
    __uint128_t total_rx = io->bytes_rx  // Bytes received (unencrypted)
                         + io->crypt_rx; // Bytes received (encrypted)
    __uint128_t total_tx = io->bytes_tx  // Bytes transmitted (unencrypted)
                         + io->crypt_tx; // Bytes transmitted (encrypted)
  @endcode
  When data is buffered (buffering is triggered by the @ref rsocket::recvline()
  method), there may be occasions where data is spared (left behind), which is
  tracked in the @ref bytes_sx and @ref crypt_sx values.  These values can be
  subtracted from the totals, if need be, as follows:
  @code{.cpp}
    #include <randolf/rsocket>
 
    std::shared_ptr<randolf::rsocket_io> io = r.net_io();
    __uint128_t total_rx = io->bytes_rx  // Bytes received (unencrypted)
                         - io->bytes_sx  // Bytes received (unencrypted spare)
                         + io->crypt_rx  // Bytes received (encrypted)
                         - io->bytes_sx; // Bytes received (encrypted spare)
    __uint128_t total_tx = io->bytes_tx  // Bytes transmitted (unencrypted)
                         + io->crypt_tx; // Bytes transmitted (encrypted)
  @endcode
  Spare bytes are only applicable to received data statistics because buffering
  is only used to receive data.
 
  This statistical data is typically used in logging, and also in applications
  that keep track of I/O on a per-user basis.
  @see rsocket::net_io()
  @see rsocket::net_io(const char*, size_t, rsocket_io*)
  @see rsocket::net_io_final()
  @see rsocket::net_io_update()
  *///=========================================================================
  struct rsocket_io : public std::mutex {
 
    /*======================================================================*//**
    @brief
    Total number of unencrypted bytes received.
    *///=========================================================================
    __uint128_t bytes_rx;
 
    /*======================================================================*//**
    @brief
    Total number of unencrypted bytes spared (received, and remains in buffer).
    *///=========================================================================
    __uint128_t bytes_sx;
 
    /*======================================================================*//**
    @brief
    Total number of unencrypted bytes transmitted.
    *///=========================================================================
    __uint128_t bytes_tx;
 
    /*======================================================================*//**
    @brief
    Total number of encrypted bytes received.
    *///=========================================================================
    __uint128_t crypt_rx;
 
    /*======================================================================*//**
    @brief
    Total number of encrypted bytes spared (received, and remains in buffer).
    *///=========================================================================
    __uint128_t crypt_sx;
 
    /*======================================================================*//**
    @brief
    Total number of encrypted bytes transmitted.
    *///=========================================================================
    __uint128_t crypt_tx;
 
    /*======================================================================*//**
    @brief
    Should always be initialized to FALSE; reserved for the @c rsocket::~rsocket
    destructor to set to TRUE.
    @see rsocket::~rsocket()
    *///=========================================================================
    bool        is_final;
 
  }; // -x- struct rsocket_io -x-
 
}; // -x- namespace randolf -x-