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();
    ulong total_rx = io->bytes_rx  // Bytes received (unencrypted)
                   + io->crypt_rx; // Bytes received (encrypted)
    ulong 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();
    ulong 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)
    ulong 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 {
    /// Total number of unencrypted bytes received
    ulong bytes_rx;
    /// Total number of unencrypted bytes spared (received, but left in buffer)
    ulong bytes_sx;
    /// Total number of unencrypted bytes transmitted
    ulong bytes_tx;
    /// Total number of encrypted bytes received
    ulong crypt_rx;
    /// Total number of encrypted bytes spared (received, but left in buffer)
    ulong crypt_sx;
    /// Total number of encrypted bytes transmitted
    ulong crypt_tx;
    /// Should always be initialized to FALSE; reserved by ~rsocket to set to TRUE
    bool  is_final;
  }; // -x- struct rsocket_io -x-
 
}; // -x- namespace randolf -x-